[disorder] / disobedience / manual / intro.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<!--
This file is part of DisOrder.
Copyright (C) 2009 Richard Kettlewell

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->
<html>
 <head>
   <title>Disobedience: Introduction</title>
   <link rel=stylesheet
         type="text/css"
         href="disobedience.css">
 </head>
 <body>
   <h1>1. Introduction</h1>

   <p>This chapter covers the following topics:</p>

   <ul>
     <li>What DisOrder and Disobedience are, and how to get them</li>
     <li>How to get a DisOrder login</li>
     <li>How to start Disobedience</li>
   </ul>

   <h2><a name=whatis>1.1 What is DisOrder?</a></h2>

   <p><a href="http://www.greenend.org.uk/rjk/disorder/">DisOrder</a>
   is a multi-user software jukebox.  It allows MP3s, OGGs, etc to be
   played either using a single sound card or over a network to many
   different computers, with multiple different people controlling
   what is played.</p>

   <p>DisOrder has three main user interfaces.</p>

   <ul>
     <li>It has a command-line interface, suitable for ad-hoc use and
     scripting.</li>

     <li>It has a web interface, usable with graphical web browsers
     (Firefox, Internet Explorer etc).</li>

     <li>It has a graphical client called Disobedience.</li>
   </ul>

   <p>This manual is about Disobedience, so it does not really cover
   installation or management issues.  However in this chapter it will
   cover a few such topics as they are necessary to getting up and
   running with Disobedience.</p>

   <!--

   <p>This diagram shows an overview of one possible setup.</p>

   <p class=image><img src="arch-simple.png"></p>

   <p>The server and web interface run on one computer.  Disobedience
   runs on a desktop computer and accesses the server via the network.
   On another system the RTP player runs and plays sound received from
   the server via its local sound card.</p>

   <p>Many other configurations are possible.  For instance the server
   could play directly to a local soundcard.  Also if Disobedience
   runs on the same computer as the RTP player then it can be used to
   stop and start the player.  Of course Disobedience can also be run
   on the same computer as the server provided it can run X11
   applications.</p>

   -->

   <h2><a name=getting>1.2 Getting DisOrder</a></h2>

   <p>There are two ways to get DisOrder.</p>

   <p>If you have a Debian system you can download the <tt>.deb</tt>
   files <a href="http://www.greenend.org.uk/rjk/disorder/">from
   DisOrder's home page</a> and install those.  There are four
   packages to choose from:</p>

   <ul>
     <li><tt>disorder.deb</tt> - the base package.  You should always
     install this.  It contains the command-line client.</li>

     <li><tt>disorder-server.deb</tt> - the server and web interface.
     Only install this if you are setting up a totally new DisOrder
     installation.  If you just want to access an existing one, you
     don't need this package.</li>

     <li><tt>disobedience.deb</tt> - the graphical client.  If you are
     reading this manual you want this package!</li>

     <li><tt>disorder-rtp.deb</tt> - the network play client.  If your
     server is set up to transmit sound over the network you will need
     this.  If it uses a local sound card then this package won't be
     useful to you.</li>

   </ul>

   <p>(At the time of writing, DisOrder is not included as part of
   Debian.)</p>

   <p>If you have another kind of Linux system, or a Mac, you must
   build from source code.  See the <tt>README</tt> file included in
   the source distribution for more details.  Note that to use
   Disobedience on a Mac, you will need X11.app.</p>

   <p>There is no Windows support (although the web interface can be
   used from Windows computers).</p>

   <h2><a name=createlogin>1.3 Getting a DisOrder login</a></h2>

   <p>The easiest way to get a DisOrder login is to access the web
   interface and set one up using that.  To do this,
   visit <tt>http://HOSTNAME/cgi-bin/disorder</tt>,
   where <tt>HOSTNAME</tt> is the name of the server where DisOrder is
   installed.  You should then be able to select the <b>Login</b>
   option at the top of the screen.</p>

   <p class=image><img src="disorder-web-login.png"></p>

   <p>Go to the <b>New Users</b> form and enter the username you want
   to use, your email address, and a password.  The password must be
   entered twice to verify you did not mistype it (since it won't be
   displayed on the screen).  When you press <b>Register</b>, you will
   be sent an email requiring you to confirm your registration.</p>

   <p class=image><img src="disorder-email-confirm.png"></p>

   <p>Your login won't be active until you click on this URL.</p>

   <p>(It might be that your installation isn't set up to allow
   automatic registration.  In that case the local sysadmin will have
   to create your login and set your initial password by hand.)</p>

   <p>Having done this you could of course just use the web interface.
   But since this is the manual for Disobedience, it is assumed that
   you want to take advantage of its more convenient design and extra
   features.</p>

   <h2><a name=starting>1.4 Starting Disobedience</a></h2>

   <p>On Debian systems it should be possible to find Disobedience in
   the menu system:</p>

   <p class=image><img src="disobedience-debian-menu.png"></p>

   <p>On other systems you will have to start it from the command line
   by typing its name at a command prompt.  You can (optionally) use
   an <tt>&amp;</tt> suffix to stop it tying up your terminal.</p>

   <p class=image><img src="disobedience-terminal.png"></p>

   <p>(Please note that Disobedience shouldn't write any messages to
   the terminal.  If it does that probably indicates a bug, which
   should <a href="https://github.com/ewxrjk/disorder/issues">be
   reported</a>.)</p>

   <h2><a name=login>1.5 Initial Login</a></h2>

   <p>The first time you run Disobedience it won't know what server to
   connect to, your username or your password, and will therefore
   display a login box.</p>

   <p class=image><img src="login.png"></p>

   <p>If Disobedience is running on a different computer to the
   server, then you should make sure the <b>Remote</b> box is ticked
   and fill in the host name (or IP address) and port number
   (&ldquo;Service&rdquo;).  If you don't know what values to use
   here, ask your local sysadmin.  If, on the other hand, Disobedience
   is running on the <i>same</i> computer as the server then you can
   leave the <b>Remote</b> box clear and it should be able to connect
   to it without using the network.</p>

   <p>In any case, you will need to enter your username and
   password, as set up earlier.</p>

   <p>Once you have logged in successfuly, Disobedience will remember
   these login settings, so it should not be necessary to enter them
   again.  If you need to change them for any reason, you can either
   select the <b>Server > Login</b> option to bring the login window
   back, or (if you prefer), edit the file <tt>~/.disorder/passwd</tt>
   directly.</p>

   <hr>

   <a href="index.html">Back to contents</a>

 </body>
</html>
Commit	Line	Data
750e9f84	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
a6e5c939 RK	2	<!--
	3	This file is part of DisOrder.
	4	Copyright (C) 2009 Richard Kettlewell
	5
	6	This program is free software: you can redistribute it and/or modify
	7	it under the terms of the GNU General Public License as published by
	8	the Free Software Foundation, either version 3 of the License, or
	9	(at your option) any later version.
	10
	11	This program is distributed in the hope that it will be useful,
	12	but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	14	GNU General Public License for more details.
	15
	16	You should have received a copy of the GNU General Public License
	17	along with this program. If not, see <http://www.gnu.org/licenses/>.
	18	-->
750e9f84 RK	19	<html>
	20	<head>
	21	<title>Disobedience: Introduction</title>
	22	<link rel=stylesheet
	23	type="text/css"
a6e5c939	24	href="disobedience.css">
750e9f84 RK	25	</head>
	26	<body>
	27	<h1>1. Introduction</h1>
	28
	29	<p>This chapter covers the following topics:</p>
	30
	31	<ul>
	32	<li>What DisOrder and Disobedience are, and how to get them</li>
	33	<li>How to get a DisOrder login</li>
	34	<li>How to start Disobedience</li>
	35	</ul>
	36
d365231a	37	<h2><a name=whatis>1.1 What is DisOrder?</a></h2>
750e9f84 RK	38
	39	<p><a href="http://www.greenend.org.uk/rjk/disorder/">DisOrder</a>
	40	is a multi-user software jukebox. It allows MP3s, OGGs, etc to be
	41	played either using a single sound card or over a network to many
	42	different computers, with multiple different people controlling
	43	what is played.</p>
	44
	45	<p>DisOrder has three main user interfaces.</p>
	46
	47	<ul>
	48	<li>It has a command-line interface, suitable for ad-hoc use and
	49	scripting.</li>
	50
	51	<li>It has a web interface, usable with graphical web browsers
4577cfe4	52	(Firefox, Internet Explorer etc).</li>
750e9f84 RK	53
	54	<li>It has a graphical client called Disobedience.</li>
	55	</ul>
	56
4577cfe4 RK	57	<p>This manual is about Disobedience, so it does not really cover
	58	installation or management issues. However in this chapter it will
	59	cover a few such topics as they are necessary to getting up and
	60	running with Disobedience.</p>
	61
4852676a RK	62	<!--
4852676a RK	63
750e9f84 RK	64	<p>This diagram shows an overview of one possible setup.</p>
750e9f84 RK	65
85c95b7f	66	<p class=image><img src="arch-simple.png"></p>
750e9f84 RK	67
	68	<p>The server and web interface run on one computer. Disobedience
	69	runs on a desktop computer and accesses the server via the network.
	70	On another system the RTP player runs and plays sound received from
	71	the server via its local sound card.</p>
	72
	73	<p>Many other configurations are possible. For instance the server
	74	could play directly to a local soundcard. Also if Disobedience
4577cfe4 RK	75	runs on the same computer as the RTP player then it can be used to
	76	stop and start the player. Of course Disobedience can also be run
	77	on the same computer as the server provided it can run X11
	78	applications.</p>
750e9f84	79
4852676a RK	80	-->
4852676a RK	81
d365231a	82	<h2><a name=getting>1.2 Getting DisOrder</a></h2>
750e9f84 RK	83
	84	<p>There are two ways to get DisOrder.</p>
	85
	86	<p>If you have a Debian system you can download the <tt>.deb</tt>
	87	files <a href="http://www.greenend.org.uk/rjk/disorder/">from
	88	DisOrder's home page</a> and install those. There are four
	89	packages to choose from:</p>
	90
	91	<ul>
	92	<li><tt>disorder.deb</tt> - the base package. You should always
	93	install this. It contains the command-line client.</li>
	94
	95	<li><tt>disorder-server.deb</tt> - the server and web interface.
	96	Only install this if you are setting up a totally new DisOrder
	97	installation. If you just want to access an existing one, you
	98	don't need this package.</li>
	99
	100	<li><tt>disobedience.deb</tt> - the graphical client. If you are
	101	reading this manual you want this package!</li>
	102
	103	<li><tt>disorder-rtp.deb</tt> - the network play client. If your
	104	server is set up to transmit sound over the network you will need
	105	this. If it uses a local sound card then this package won't be
	106	useful to you.</li>
	107
	108	</ul>
	109
	110	<p>(At the time of writing, DisOrder is not included as part of
	111	Debian.)</p>
	112
	113	<p>If you have another kind of Linux system, or a Mac, you must
	114	build from source code. See the <tt>README</tt> file included in
4577cfe4 RK	115	the source distribution for more details. Note that to use
4577cfe4 RK	116	Disobedience on a Mac, you will need X11.app.</p>
750e9f84 RK	117
	118	<p>There is no Windows support (although the web interface can be
	119	used from Windows computers).</p>
	120
bf47a016	121	<h2><a name=createlogin>1.3 Getting a DisOrder login</a></h2>
750e9f84 RK	122
	123	<p>The easiest way to get a DisOrder login is to access the web
	124	interface and set one up using that. To do this,
	125	visit <tt>http://HOSTNAME/cgi-bin/disorder</tt>,
	126	where <tt>HOSTNAME</tt> is the name of the server where DisOrder is
	127	installed. You should then be able to select the <b>Login</b>
	128	option at the top of the screen.</p>
	129
85c95b7f	130	<p class=image><img src="disorder-web-login.png"></p>
750e9f84 RK	131
	132	<p>Go to the <b>New Users</b> form and enter the username you want
	133	to use, your email address, and a password. The password must be
	134	entered twice to verify you did not mistype it (since it won't be
	135	displayed on the screen). When you press <b>Register</b>, you will
	136	be sent an email requiring you to confirm your registration.</p>
	137
85c95b7f	138	<p class=image><img src="disorder-email-confirm.png"></p>
750e9f84 RK	139
	140	<p>Your login won't be active until you click on this URL.</p>
	141
ebf1f558 RK	142	<p>(It might be that your installation isn't set up to allow
	143	automatic registration. In that case the local sysadmin will have
	144	to create your login and set your initial password by hand.)</p>
750e9f84	145
4577cfe4 RK	146	<p>Having done this you could of course just use the web interface.
	147	But since this is the manual for Disobedience, it is assumed that
	148	you want to take advantage of its more convenient design and extra
	149	features.</p>
	150
d365231a	151	<h2><a name=starting>1.4 Starting Disobedience</a></h2>
750e9f84 RK	152
	153	<p>On Debian systems it should be possible to find Disobedience in
	154	the menu system:</p>
	155
85c95b7f	156	<p class=image><img src="disobedience-debian-menu.png"></p>
750e9f84 RK	157
	158	<p>On other systems you will have to start it from the command line
	159	by typing its name at a command prompt. You can (optionally) use
	160	an <tt>&</tt> suffix to stop it tying up your terminal.</p>
	161
85c95b7f	162	<p class=image><img src="disobedience-terminal.png"></p>
750e9f84	163
4577cfe4 RK	164	<p>(Please note that Disobedience shouldn't write any messages to
4577cfe4 RK	165	the terminal. If it does that probably indicates a bug, which
847e2b27	166	should <a href="https://github.com/ewxrjk/disorder/issues">be
4577cfe4 RK	167	reported</a>.)</p>
4577cfe4 RK	168
d365231a	169	<h2><a name=login>1.5 Initial Login</a></h2>
4577cfe4 RK	170
	171	<p>The first time you run Disobedience it won't know what server to
	172	connect to, your username or your password, and will therefore
	173	display a login box.</p>
	174
85c95b7f	175	<p class=image><img src="login.png"></p>
4577cfe4 RK	176
	177	<p>If Disobedience is running on a different computer to the
	178	server, then you should make sure the <b>Remote</b> box is ticked
	179	and fill in the host name (or IP address) and port number
	180	(“Service”). If you don't know what values to use
	181	here, ask your local sysadmin. If, on the other hand, Disobedience
	182	is running on the <i>same</i> computer as the server then you can
	183	leave the <b>Remote</b> box clear and it should be able to connect
	184	to it without using the network.</p>
	185
	186	<p>In any case, you will need to enter your username and
	187	password, as set up earlier.</p>
	188
	189	<p>Once you have logged in successfuly, Disobedience will remember
	190	these login settings, so it should not be necessary to enter them
	191	again. If you need to change them for any reason, you can either
a9ace56d RK	192	select the <b>Server > Login</b> option to bring the login window
a9ace56d RK	193	back, or (if you prefer), edit the file <tt>~/.disorder/passwd</tt>
4577cfe4 RK	194	directly.</p>
4577cfe4 RK	195
f326f12d RK	196	<hr>
	197
	198	<a href="index.html">Back to contents</a>
	199
750e9f84 RK	200	</body>
750e9f84 RK	201	</html>