docs: update structure and create links between pages (#1611)
* docs: rework files structure * rewrite documentation entrypoint * update category files and use yml * add manuals entry page * update admin-manual titles and page order * create releases sections * move ssl configuration to reverse proxy * docs: update website vars and links * update release note codeblock syntax key * resurect troubleshooting guide * Update freeipa custom auth documentation * add notice about the state of the documentation * update the backup documentation * tmp: allow to deploy the website for preview * Don't use require.resolve for plugins * Update the main page link dest * update development environment title * rewrite the install/upgrade/migrate as guides * update website docs sections links * Fix urls * move release note to documentation * move home links to vars files * tmp: update deploy url * add react to tsconfig to handle jsx linting * fix: replace absolute url to relative path to files * tmp: allow CI Website dpeloy on working branch * Update release note title * use default syntax highlighting theme * update the troubleshooting guide * Wording * use CodeBlock components * Better prose * remove api_client config section * fix prose errors * update import prefix for vars file * reroder docs manuals links * use sentence capitalization for page titles * Wording * missing word * Update note about syslog log file * wording
This commit is contained in:
Jonas L
GitHub
parent
5769821995
commit
3ec85d7821
107 changed files with 682 additions and 512 deletions
13
docs/developer-manual/README.md
Normal file
13
docs/developer-manual/README.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
title: Developer manual
|
||||
---
|
||||
|
||||
Welcome to the **LibreTime developer manual**, you should find guides to integrate LibreTime and tools to improve and contribute to LibreTime.
|
||||
|
||||
## Integrate LibreTime
|
||||
|
||||
- :construction: Work in progress
|
||||
|
||||
## Improve and contribute to LibreTime
|
||||
|
||||
- :construction: Work in progress
|
||||
2
docs/developer-manual/_category_.yml
Normal file
2
docs/developer-manual/_category_.yml
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
label: Developer manual
|
||||
position: 40
|
||||
131
docs/developer-manual/environment.md
Normal file
131
docs/developer-manual/environment.md
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
---
|
||||
title: Development environment
|
||||
---
|
||||
|
||||
## Vagrant
|
||||
|
||||
To use Vagrant, you need to install a virtualization engine: [VirtualBox](https://www.virtualbox.org) or Libvirt. The [vagrant-vbguest] package on Github can help maintain guest extensions on host systems using VirtualBox.
|
||||
|
||||
:::tip
|
||||
|
||||
If you try run a libvirt provided box after using a VirtualBox one, you will receive an
|
||||
error:
|
||||
|
||||
```
|
||||
Error while activating network:
|
||||
Call to virNetworkCreate failed: internal error: Network is already in use by interface vboxnet0.
|
||||
```
|
||||
|
||||
This is fixed by stopping virtualbox and re-creating the vagrant box:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop virtualbox
|
||||
vagrant destroy ubuntu-bionic
|
||||
vagrant up ubuntu-bionic --provider=libvirt
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Installing Libvirt
|
||||
|
||||
On Debian and Ubuntu:
|
||||
|
||||
1. Install Vagrant
|
||||
|
||||
```bash
|
||||
sudo apt install vagrant vagrant-libvirt libvirt-daemon-system vagrant-mutate libvirt-dev
|
||||
sudo usermod -aG libvirt $USER
|
||||
```
|
||||
|
||||
2. Reboot your computer, and then run
|
||||
|
||||
```bash
|
||||
vagrant box add bento/ubuntu-18.04 --provider=virtualbox
|
||||
vagrant mutate bento/ubuntu-18.04 libvirt
|
||||
vagrant up ubuntu-bionic --provider=libvirt
|
||||
```
|
||||
|
||||
On other distributions, you will need to install [libvirt](https://libvirt.org/) and `vagrant-mutate` and then run
|
||||
|
||||
```bash
|
||||
vagrant plugin install vagrant-libvirt
|
||||
sudo usermod -a -G libvirt $USER
|
||||
|
||||
# Reboot
|
||||
|
||||
vagrant plugin install vagrant-mutate
|
||||
vagrant box fetch bento/ubuntu-18.04
|
||||
vagrant mutate bento/ubuntu-18.04 libvirt
|
||||
vagrant up ubuntu-bionic --provider=libvirt
|
||||
```
|
||||
|
||||
### Starting LibreTime Vagrant
|
||||
|
||||
To get started you clone the repo and run `vagrant up`. The command accepts a parameter to
|
||||
change the default provider if you have multiple installed. This can be done by appending
|
||||
`--provider=virtualbox` or `--provider=libvirt` as applicable.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/libretime/libretime.git
|
||||
cd libretime
|
||||
vagrant up ubuntu-bionic
|
||||
```
|
||||
|
||||
If everything works out, you will find LibreTime on [port 8080](http://localhost:8080)
|
||||
and Icecast on [port 8000](http://localhost:8000).
|
||||
|
||||
Once you reach the web setup GUI you can click through it using the default values. To
|
||||
connect to the vagrant machine you can run `vagrant ssh ubuntu-bionic` in the libretime
|
||||
directory.
|
||||
|
||||
### Alternative OS installations
|
||||
|
||||
With the above instructions LibreTime is installed on Ubuntu Bionic. The Vagrant setup
|
||||
offers the option to choose a different operation system according to you needs.
|
||||
|
||||
| OS | Command | Comment |
|
||||
| ------------ | ---------------------------- | ----------------------------------------------------------- |
|
||||
| Debian 10 | `vagrant up debian-buster` | Install on Debian Buster. |
|
||||
| Debian 11 | `vagrant up debian-bullseye` | Install on Debian Bullseye. |
|
||||
| Ubuntu 18.04 | `vagrant up ubuntu-bionic` | Install on Ubuntu Bionic Beaver. |
|
||||
| Ubuntu 20.04 | `vagrant up ubuntu-focal` | Install on Ubuntu Focal Fossa. |
|
||||
| CentOS | `vagrant up centos` | CentOS 8 with native systemd support and activated SELinux. |
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If anything fails during the initial provisioning step you can try running `vagrant provision`
|
||||
to re-run the installer.
|
||||
|
||||
If you only want to re-run parts of the installer, use `--provision-with $step`. The
|
||||
supported steps are `prepare` and `install`.
|
||||
|
||||
## Multipass
|
||||
|
||||
[Multipass](https://multipass.run) is a tool for easily setting up Ubuntu VMs on Windows, Mac, and Linux.
|
||||
Similar to Docker, Multipass works through a CLI. To use, clone this repo and then create a new Multipass VM.
|
||||
|
||||
```
|
||||
git clone https://github.com/libretime/libretime.git
|
||||
cd libretime
|
||||
multipass launch bionic -n ltTEST --cloud-init cloud-init.yaml
|
||||
multipass shell ltTEST
|
||||
```
|
||||
|
||||
Multipass isn't currently able to do an automated install from the cloud-init script.
|
||||
After you enter the shell for the first time, you will still need to [run the LibreTime installer](../admin-manual/setup/install.md).
|
||||
|
||||
The IP address of your new VM can be found by running `multipass list`. Copy and paste it into your web browser to access the LibreTime interface and complete the setup wizard.
|
||||
|
||||
You can stop the VM with `multipass stop ltTEST` and restart with `multipass start ltTEST`.
|
||||
If you want to delete the image and start again, run `multipass delete ltTEST && multipass purge`.
|
||||
|
||||
### Cloud-init options in cloud-init.yaml
|
||||
|
||||
You may wish to change the below fields as per your location.
|
||||
|
||||
```yaml
|
||||
timezone: America/New York # change as needed
|
||||
ntp:
|
||||
pools: ["north-america.pool.ntp.org"]
|
||||
servers: ["0.north-america.pool.ntp.org", "0.pool.ntp.org"]
|
||||
```
|
||||
70
docs/developer-manual/legacy-api.md
Normal file
70
docs/developer-manual/legacy-api.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: LibreTime API usage
|
||||
---
|
||||
|
||||
:::info
|
||||
|
||||
We're in the process of rewriting LibreTime's API. This page contains the instructions for the current version, written in PHP.
|
||||
|
||||
:::
|
||||
|
||||
The LibreTime API enables many types of information about the broadcast schedule and configuration to be retrieved from the LibreTime server. Other than the live-info and week-info data fetched by website widgets (see the chapter _Exporting the schedule_), all API requests must be authenticated using the secret API key stored in the file `/etc/airtime/api_client.cfg` on the LibreTime server. This key is autogenerated during LibreTime installation and should be unique for each server.
|
||||
|
||||
If you intend to use the LibreTime API across a public network, for security reasons it is highly recommended that all API requests are sent over encrypted https: and that the web server is configured to accept requests to the api/ directory from specific host names or IP addresses only.
|
||||
|
||||
The format of API requests is:
|
||||
|
||||
```
|
||||
https://libretime.example.com/api/api-action/format/json/api_key/XXXXXX
|
||||
```
|
||||
|
||||
where api-action is the type of request and XXXXXX is the secret API key. Available actions include:
|
||||
|
||||
- on-air-light - return true if the station is on air
|
||||
- status - get the status of LibreTime components and resource usage
|
||||
- version - returns the version of LibreTime installed
|
||||
- get-files-without-silan-value - list files for which silence detection has not yet been performed
|
||||
- get-stream-setting - gets the settings of LibreTime output streams
|
||||
- get-stream-parameters - gets the parameters of LibreTime output streams
|
||||
|
||||
For example, using the action _get-stream-setting_ returns the following output for the first configured stream:
|
||||
|
||||
```json
|
||||
{"keyname":"s1_type","value":"ogg","type":"string"},
|
||||
|
||||
{"keyname":"s1_host","value":"streaming.example.com","type":"string"},
|
||||
|
||||
{"keyname":"s1_port","value":"8000","type":"integer"},
|
||||
|
||||
{"keyname":"s1_mount","value":"airtime_128","type":"string"},
|
||||
|
||||
{"keyname":"s1_url","value":"http:\/\/airtime.sourcefabric.org","type":"string"},
|
||||
|
||||
{"keyname":"s1_description","value":"Airtime Radio! Stream #1","type":"string"},
|
||||
|
||||
{"keyname":"s1_genre","value":"Screamo","type":"string"},
|
||||
```
|
||||
|
||||
which is enough information to construct a player widget dynamically. (s1_url is the station's homepage, not the stream URL). The same information is provided with an s2\_ prefix for the second stream, and s3\_ prefix for the third stream.
|
||||
|
||||
Some API requests require the directory ID number to be specified as _dir_id_ including:
|
||||
|
||||
- list-all-files - list files in the specified directory
|
||||
- get-files-without-replay-gain - list files in the specified directory for which ReplayGain has not been calculated yet
|
||||
|
||||
For example, using a request such as:
|
||||
|
||||
```
|
||||
http://libretime.example.com/api/list-all-files/format/json/api_key/XXXXXX/dir_id/1/
|
||||
```
|
||||
|
||||
returns the full path to each media file in the LibreTime storage directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"files": [
|
||||
"imported/1/Mark Ronson feat. Saigon/Here Comes the Fuzz/7-Diduntdidunt-unknown.flac",
|
||||
"imported/1/Jimi Tenor & Tony Allen/Inspiration Information/3-Selfish Gene-128kbps.mp3"
|
||||
]
|
||||
}
|
||||
```
|
||||
BIN
docs/developer-manual/widgets-widgets_player.png
Normal file
BIN
docs/developer-manual/widgets-widgets_player.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
BIN
docs/developer-manual/widgets-widgets_schedule.png
Normal file
BIN
docs/developer-manual/widgets-widgets_schedule.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
BIN
docs/developer-manual/widgets-widgets_settings.png
Normal file
BIN
docs/developer-manual/widgets-widgets_settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
33
docs/developer-manual/widgets.md
Normal file
33
docs/developer-manual/widgets.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: Widgets
|
||||
---
|
||||
|
||||
Bring your LibreTime broadcast to your website with embeddable widgets! LibreTime comes with two widgets: a streaming player and a schedule. Both widgets use iframes to display and can be placed wherever embeddable code can on a website.
|
||||
|
||||
## Getting started
|
||||
|
||||
Before using the widgets, make sure LibreTime's Public API is enabled in **Settings** > **General**.
|
||||
|
||||
|
||||
|
||||
:::tip Note
|
||||
|
||||
LibreTime widgets cannot function through VPNs or SSH tunneling. The instance must be accessible from the internet for the widgets to work.
|
||||
|
||||
:::
|
||||
|
||||
## Streaming player widget
|
||||
|
||||
The streaming player widget inserts your LibreTime stream into your website. One example is from [WRCS Community Radio](https://wcrsfm.org/) in Columbus, Ohio, USA.
|
||||
|
||||
<iframe frameborder="0" width="400" height="235" src="http://broadcast.wcrsfm.org/embed/player?stream=auto&title=Now Playing"></iframe>
|
||||
|
||||
|
||||
|
||||
From **Widgets** > **Player**, enter a title for your streaming widget and select what stream you'd like to use. All selectible streams must first be configured in **Settings** > **Streams** (see [Settings](../user-manual/settings.md)). **Auto detect** should be fine for most.
|
||||
|
||||
## Show schedule widget
|
||||
|
||||
|
||||
|
||||
The show schedule widget displays the upcoming shows for the next seven days. There are no customizable settings for this widget.
|
||||
Loading…
Add table
Add a link
Reference in a new issue