Reorganizing tutorials

This commit is contained in:
Zachary Klosko 2020-05-10 15:37:46 -04:00
parent 65d836905e
commit 4eb211c47f
35 changed files with 17 additions and 4 deletions

View file

@ -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.  

View file

@ -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.

Binary file not shown.

After

Width:  |  Height:  |  Size: 57 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 49 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 35 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

View file

@ -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.

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 226 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

14
docs/tuts/uninstall.md Normal file
View file

@ -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

View file

@ -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.