Reorganizing tutorials

docs/tuts/backing-up-the-server/index.md

@@ -0,0 +1,71 @@
+The following shell commands can be used for database backup and restore on a
+running *PostgreSQL* server in an LibreTime system.
+
+You can dump the entire database to a zipped file with the combination of the
+**pg\_dumpall** command and **gzip**. The **pg\_dumpall** command is executed
+as the user *postgres*, by using the **sudo** command and the **-u** switch. It
+is separated from the **gzip** command with the pipe symbol.
+
+```bash
+sudo -u postgres pg_dumpall | gzip -c > libretime-backup.gz
+```
+
+This command can be automated to run on a regular basis using the standard
+**cron** tool on your server.
+
+When restoring a production database on a cleanly installed LibreTime system, it
+may be necessary to drop the empty database that was created during the new
+installation, by using the **dropdb** command. Again, this command is executed
+with **sudo** as the user *postgres*: 
+
+```bash
+sudo -u postgres dropdb airtime
+```
+
+This **dropdb** command above is necessary to avoid 'already exists' errors on
+table creation when overwriting an empty LibreTime database in the next step.
+These errors might prevent some data from being restored, such as user account
+data.
+
+To restore, first unzip the backup file with **gunzip**, then use the **psql**
+command as the *postgres* user:
+
+```bash
+gunzip libretime-backup.gz
+sudo -u postgres psql -f libretime-backup
+```
+
+You should now be able to log in to the LibreTime web interface in the usual way.
+
+For safety reasons, your regular database backups should be kept in a directory
+which is backed up by your storage backup tool of choice; for example, the
+*/srv/airtime/database\_backups* directory. This should ensure that a storage
+restore can be made along with a matching and complete version of the LibreTime
+database from the day that the storage backup was made. 
+
+Storage backup
+--------------
+
+Backing up the LibreTime database with **pg\_dumpall** will not back up the
+LibreTime media storage server, which is likely to need a great deal more backup
+space. Creating a compressed file from hundreds of gigabytes of storage server
+contents is likely to take a very long time, and may have little benefit for the
+amount of CPU power used, if the media files are already stored in a highly
+compressed format. It is also impractical to copy very large backup files across
+the network on a daily basis.
+
+Instead, it is preferable to use an incremental backup technique to synchronize
+the production LibreTime server storage with a backup server each day or night. If
+the backup server also contains an LibreTime installation, it should be possible
+to switch playout to this second machine relatively quickly, in case of a
+hardware failure or other emergency on the production server.
+
+A standard incremental backup tool on GNU/Linux servers is *rsync*
+[(http://rsync.samba.org/)](http://rsync.samba.org/)) which can be installed
+using the package manager of your GNU/Linux distribution. However, incremental
+backup alone cannot help in the scenario where a file which later proves to be
+important has been deleted by an administrator. For backups that can be rolled
+back to restore from an earlier date than the current backup, the tool
+*rdiff-backup*
+[(http://www.nongnu.org/rdiff-backup/](http://www.nongnu.org/rdiff-backup/)) can
+be deployed.  

docs/tuts/getting-started/index.md

@@ -0,0 +1,100 @@
+# Getting Started
+
+If the server is only being used for LibreTime and has a web browser installed,
+you can access the administration interface directly on that server by opening
+the address:
+
+    http://localhost/
+
+If you have set up LibreTime so that it can be accessed from other computers,
+you would use a domain name instead. For example:
+
+    https://libretime.example.com/
+
+You can log in for the first time with the user name *admin* and the password
+*admin*. Your browser should automatically focus on the
+**Username** field.
+
+![](../on-air-in-60-seconds/static/Screenshot559-Log_in.png)
+
+You will see a link **Reset password** below the password field, which enables
+users to obtain a password reminder by email. You will need to have a
+mailserver configured to work with PHP for this to work. There is an issue open
+to add documentation for this
+([#724](https://github.com/LibreTime/libretime/issues/724)).
+
+![](static/Screenshot467-Reset_password_link.png) 
+
+The **E-mail** address you enter must match the address stored in the database
+for your **Username**.
+
+![](static/Screenshot468-Restore_password.png)
+
+
+The Master Panel
+----------------
+
+The **Master Panel** is present at the top of every page of the LibreTime
+interface. On the left hand side, the Master Panel displays the details of the
+**Previous** file played out, the current file playing (with an orange progress
+bar and time elapsed/time remaining), and the details of the **Next** file due
+to play. It also displays the name and scheduled time of the current show, with
+a blue progress bar.
+
+![](static/Screenshot-MasterPanel.png)
+
+Beneath this side of the Master Panel is the main navigation menu. We'll be
+looking at the contents of these menus in the following chapters of this book.
+
+![](static/Screenshot-MainMenu.png)
+
+On the right hand side of the Master Panel are the switches for the **Source
+Streams**, which enable you to switch from scheduled play to remote live
+sources, and back. (See the chapter *Stream settings* for details of this
+feature). The **On Air** indicator turns from dark grey to red whenever audio
+is being played out. Underneath this indicator is a **Listen** button, which
+opens a pop-up player that can be used to audition the available playout
+streams.
+
+There is also a clock indicating the **Station time** and time zone. Beneath
+the clock and just to the left, the name of the user currently logged in is
+displayed, and there is the link for you to **Logout**. 
+
+![](static/Screenshot469-On_Air_light.png)
+
+Clicking the username link opens a page in which you can update your LibreTime
+password, contact details, language and time zone preferences. Click the
+**Save** button once you have made the changes that you require.
+
+![](static/Screenshot470-User_settings.png)
+
+Checking an Icecast server
+--------------------------
+
+If you have installed an Icecast streaming media server, you can check that
+Icecast is running by opening its default server port of 8000 in your web
+browser. For example, on the server itself, you can use:
+
+    http://localhost:8000
+
+or from another machine, using the domain name of the Icecast server:
+
+    http://streaming.example.com:8000
+
+You should see the Icecast status page, with details of any connections that
+your LibreTime server has made to this Icecast server. If you have only just
+installed LibreTime, there may not be any media playing out yet.
+
+![](static/Screenshot293-Icecast_status_page.png)
+
+Reverse Proxy Connections
+-------------------------
+In some deployments, the LibreTime server is deployed behind a reverse proxy,
+for example in containerization use-cases such as Docker and LXC. LibreTime
+makes extensive use of its API for some site functionality, which causes
+[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+to occur. By default, CORS requests are blocked by your browser and the origins
+need to be added to the **Allowed CORS URLs** block in
+[**General Settings**](/manual/general/). These origins should include any
+domains that will be used externally to connect to your reverse proxy that you
+want handled by LibreTime.

docs/tuts/live-shows-with-mixxx/index.md

@@ -0,0 +1,44 @@
+Mixxx is a cross-platform Open Source application for DJs, available from <http://www.mixxx.org/>
+
+Installed on a desktop or laptop computer, Mixxx complements your LibreTime server to provide a complete system for both live and scheduled broadcasting. Although Mixxx has many features designed for dance music DJs that require beat matching and pitch independent time stretching, the program can be used for any kind of manually triggered broadcast playout, including live speech shows such as news or current affairs.
+
+Mixxx supports a wide variety of popular hardware control surfaces, which can be connected to your computer using a USB cable. A control surface might replace or augment an analogue mixer in your studio, depending on your live mixing and playout requirements.
+
+Sound cards
+-----------
+
+If you wish to use LibreTime and Mixxx on the same machine, you will need two or more sound cards, as each program requires exclusive access to the sound hardware. Otherwise, you may see an error message that Mixxx cannot access the sound device.
+
+![](static/Screenshot374-Mixxx-soundcard_busy.png) 
+
+The solution is to configure Mixxx to use additional sound cards by clicking **Options**, **Preferences**, then **Sound Hardware** in the main Mixxx menu. Select devices other than the ALSA default of *hw:0,0* for at least the **Master** and **Headphones** outputs. Then click the **OK** button.
+
+![](static/Screenshot375-Mixxx_sound_hardware.png)
+
+Sharing storage
+---------------
+
+If you make the LibreTime server's storage directory */srv/airtime/stor/* accessible to a desktop machine as a read-only location, Mixxx will accept that location as its default music library when starting up for the first time. (This location can also be configured after installation by clicking **Options**, **Preferences**, then **Library** in the main Mixxx menu).
+
+![](static/Screenshot103-Mixxx_Preferences.png)
+
+You may need to adjust file and directory permissions so that the storage directory has read access from the desktop user account. Enabling write access directly to the storage server is not recommended, as this would allow desktop users to delete files which might be needed for playout later.
+
+If the filesystem path has been configured correctly, the metadata for the files in the LibreTime storage server will be displayed in the main window of the Mixxx interface. Individual files from the LibreTime storage server can then be added to either of Mixxx's live players with a right-click on the filename, or by using the appropriate hardware buttons on a control surface. Therefore it is possible to manage the station's storage archive remotely and collaboratively through LibreTime, while using Mixxx as the live playout client in multiple, remote studios.
+
+![](static/Screenshot102-Mixxx_with-Airtime_storage.png)
+
+The LibreTime storage archive can be exported like any other file server share. The method that you implement would depend on the operating system of your desktop client machines, and whether they were on the same local network as the LibreTime server, or remote.
+
+For performance and redundancy reasons it is advisable to cache files required for a particular show on the client machine where Mixxx is installed. For example, for a GNU/Linux client machine, a nightly **rsync** download of new media in the archive would guard against network problems at playout time potentially disrupting a broadcast at a remote studio.
+
+Mixxx users can also record a show, and then upload it through the LibreTime web interface on a local or remote server for collaborative or user-generated broadcasts.
+
+Streaming from Mixxx into LibreTime
+---------------------------------
+
+Mixxx 1.9.0 or later includes a live streaming client which, like LibreTime, is compatible with the **Icecast** and **SHOUTcast** media servers. This feature can also be used to stream from Mixxx directly into LibreTime, using either the **Show Source** or **Master Source**.
+
+![](static/Screenshot369-Mixxx_streaming_preferences.png)
+
+To configure **Mixxx** for streaming into LibreTime, click **Options**, **Preferences**, then **Live Broadcasting** on the main Mixxx menu. For server **Type**, select the default of **Icecast 2**. For **Host**, **Mount**, **Port**, **Login** and **Password**, use the **Input Stream Settings** configured in the LibreTime **Streams** page, on LibreTime's **System** menu. See the chapter *Stream settings* for remote input connection details.

docs/tuts/uninstall.md

@@ -0,0 +1,14 @@
+Uninstall LibreTime
+-------------------
+
+Hopefully it wasn't something that we did, but if you need to uninstall LibreTime for
+any reason, cd to the directory of the installer and run `sudo ./uninstall` and follow the prompts.
+If allowed, the installer will **permanently** delete all databases and uploaded content relative to
+LibreTime.
+
+If it was something we did, please open an issue request on our Github page, located
+[here](https://github.com/LibreTime/libretime/issues).
+
+Until we meet again, best of luck.
+
+<3 The LibreTime team

docs/tuts/upgrading/index.md

@@ -0,0 +1,40 @@
+## LibreTime versioning
+
+LibreTime 3.x versions support upgrading from Airtime 2.5.x versions. LibreTime follows the [Semantic Versioning (semver)](http://semver.org/spec/v2.0.0.html) standards.
+
+In a nutshell, given a version number MAJOR.MINOR.PATCH we increment the:
+
+1. MAJOR version when we make incompatible API changes,
+2. MINOR version when we add functionality in a backwards-compatible manner, and
+3. PATCH version when we make backwards-compatible bug fixes.
+
+Any pre-release versions of LibreTime are denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. This pre-release indicates that the version is unstable in a sense that it might contain incomplete features or not satisfy the intended compatibility requirements as per semver.
+
+## Upgrading 
+
+Before upgrading a production LibreTime server, you should back up both the PostgreSQL database and the storage server used by LibreTime. This is especially important if you have not already set up a regular back up routine. This extra back up is a safety measure in case of accidental data loss during the upgrade, for example due to the wrong command being entered when moving files. See [Backing up the server](../backing-up-the-server/) in this manual for details of how to perform these back ups.
+
+The LibreTime [installation script](../install) will detect an existing LibreTime or Airtime deployment and back up any configuration files that it finds. We recommend taking your own manual backups of the configuration yourself nevertheless.  The install script also tries to restart the needed services during an upgrade. In any case you should monitor if this happened and also take a quick look at the logs files to be sure everything is still fine. Now might be the time to reboot the system or virtual machine LibreTime is running on since regular reboots are part of a healthy system anyway.
+
+After the upgrade has completed, you may need to clear your web browser's cache  before logging into the new version of the LibreTime administration interface. If the playout engine starts up and detects that a show should be playing at the  current time, it will skip to the correct point in the current item and start playing. 
+
+There will be tested ways to switch from a LibreTime pre-release to a packaged version of LibreTime.
+
+Airtime 2.5.x versions support upgrading from version 2.3.0 and above. If you are
+running a production server with a version of Airtime prior to 2.3.0, you should
+upgrade it to version 2.3.0 before continuing. 
+
+In Airtime 1.9.0 onwards, the concept of *linked files* was replaced with the
+concept of *watched folders*. If you are upgrading from a version of Airtime 
+earlier than 1.9.0 and you have previously linked files, the folders they are
+in will not be watched until you add them to your watched folder list. See
+[Media Folders](../media-folders) for more details.
+
+Upgrading the server distribution
+---------------------------------
+
+After your LibreTime server has been deployed for a few years, you may need to
+upgrade the GNU/Linux distribution that it runs in order to maintain security
+update support. If the upgrade does not go smoothly, it may cause significant
+downtime, so you should always have a fallback system available during the 
+upgrade to ensure broadcast continuity.