- Installing Showergel requires
We assume you already know the basics of Liquidsoap and its script language. If you have never played with only Liquidsoap, we advise you read at least its quick start guide. Then you might jump to Showergel’s quickstart.liq.
Install Showergel by running
pip3 install showergel (maybe replace
Then you’ll need to set-up your first instance. Before that, let’s explain briefly what it means.
What’s a Showergel instance ?¶
Technically, it is an instance of the
It’s an HTTP server:
it is able to serve an interface you can open in your browser,
and to answer queries called from your Liquidsoap script.
Functionally, an instance is the companion of one Liquidsoap stream.
The two programs will communicate with each other to produce and follow this stream.
An instance relies on some configuration (a
.toml file) and a database (an SQLite file).
It can be installed as a system service,
named after information you provide at set-up time.
If you are running multiple Liquidsoap streams on the same machine, you’ll have to set up one Showergel instance per stream. In that case,
each instance should have a different name
each instance should run on a different port number
We advise you to put all instance’s files (configuration, DB, logs)
in the same folder as the corresponding
When running multiple Liquidsoaps, create a folder per instance.
Create an instance with the interactive installer¶
Run the interactive installer by calling
It will explain on the terminal what is happening and what to do from here.
If you stick to defaults, the instance’s basename will be
so the installer will:
create a database (
showergel.db) and a configuration file (
showergel.toml) in the current directory,
create a systemd user service called
showergel; in other words you can
systemctl --user status|start|stop|restart showergel.
enable the service and systemd’s lingering so Showergel will start automatically at boot time.
The installer allows you to create another systemd user service, for your Liquidsoap script.
This is recommended, because then systemd will automatically launch both Showergel and Liquidsoap,
and restart them when a crash happens.
If you do so, the installer creates two systemd services with the same basename:
radio_gel (Showergel service associated to
radio_soap (wrapper for the Liquidsoap script you provided for
If you choose to not create a service, you will have to (re)start Showergel
manually by calling
Before exiting, the installer gives a recap of its actions.
Please pay attention to the installer’s recap: it lists how to run/stop Showergel and gives pointers to important files. Read it twice and copy this information safely.
Unless you configured another port, Showergel will be available at http://localhost:2345/. Showergel’s and Liquidsoap’s configurations are coupled. In perticular, they should define which port/URL should be used to contact each other: see Configuring Showergel and Showergel integration in Liquidsoap scripts.
If you installed Showergel as a system service,
don’t forget to restart showergel’s service after editing its configuration file.
If you installed your Liquidsoap script as a system service,
restart this service after editing the script - and after running
liquidsoap --check my_script.liq !
In both cases, log files are in the same folder as instance’s other files.
Install for back-end development¶
When developping, your Liquidsoap script and Showergel should be launched manually.
showergel_install --dev to create an empty database (
and a basic configuration file (
in the current folder.
Read (and edit, maybe)
launch Liqudisoap, then run
You’ll likely want to enable the detailed log by setting
logger_root section of the toml file.
pytest. See also Package and publish Showergel.
Install for front-end development¶
To modify the front-end, you must beforehand install Yarn and Vue_CLI,
yarn install from the repository root.
Start the live-building server with
If you don’t have time to install the whole back-end,
you can call the demo app by creating a
front/.env file that contains:
Similarly, a fully-working HTML/JS/CSS build is included in this repository,
so one doesn’t have to install
yarn and Vue while working on the back-end.
Those files are generated by
Please do not commit modifications in the
In order to avoid complex and useless conflicts, commits concerning this folder
should only happen on the
Deploy to Heroku in demo mode¶
In demo mode, the application starts by putting fake data in the database.
It’s enabled by putting
demo = True in the configuration file’s
Source repository includes such a configuration, so you can create and push the app right after cloning:
heroku create --region eu git push heroku main heroku logs --tail
We might need to update
requirements.txt from time to time:
poetry export --dev --without-hashes -f requirements.txt --output requirements.txt
--dev is here because
requirements.txt is also used by ReadTheDocs
to compile the present documentation, which requires a Sphinx extension.