Install In Docker

• Why Docker?
• Try-out qToggleServer
• Production-ready Setup
  • Data Volume
  • Configuration File
  • Timezone
  • Persistence Driver
  • Versions
  • Detached Mode
• Installing Add-ons
• Using docker compose
  • Simple Example
  • Running docker compose
  • Redis
• Upgrading To New Version

---

Why Docker?

Using docker is probably the easiest way to try out qToggleServer without altering your system or installing otherwise unnecessary packages.

Another use case for a dockerized qToggleServer is when you already have other services running in Docker containers on your server and you want to add qToggleServer to your stack.

Try-out qToggleServer

On your Docker machine, simply run:

$ docker run -it --rm -p 8888:8888 qtoggle/qtoggleserver:stable

Flags -it will start an interactive process on your terminal, while --rm will remove the container after you're done. -p 8888:8888 exposes and publishes internal port 8888 to host's port 8888. You'll be able to observe the server log on your terminal. When you're done playing with it, just hit Ctrl+C.

Now point your browser to http://localhost:8888 and you should be presented with a login screen. Follow the Getting Started page for next steps.

⚠️ Keep in mind that everything you do in this session is temporary and that your changes will be lost when you exit the container.

Production-ready Setup

If you want to run qToggleServer in a production environment, you'll have to:

• use a persisted volume, so that your data is properly saved
• supply your configuration instead of relying on defaults
• run the container in detached (background) mode

Data Volume

All qToggleServer data (configuration, database, add-ons) lives in /data inside your container. Use -v when running your container to pass it as a volume associated to a path on your host machine:

$ docker run -it --rm -p 8888:8888 \
             -v /path/on/host/qtoggleserver-data:/data \
             qtoggle/qtoggleserver:stable

Configuration File

When you run the container for the first time, it will place the default configuration file in etc/qtoggleserver.conf, on the data volume. You can edit it or use your own qtoggleserver.conf.

After changing the configuration file, you need to restart the container. If you started it with -it (i.e. in foreground), you can simply hit Ctrl+C and start it again.

Timezone

You should set the timezone of your container by passing the TZ environment variable using -e:

$ docker run -it --rm -p 8888:8888 \
             -v /path/on/host/qtoggleserver-data:/data \
             -e TZ=Europe/Berlin \
             qtoggle/qtoggleserver:stable

Persistence Driver

By default, qToggleServer uses a JSON file to save data that needs to be persisted. You'll find it under the name qtoggleserver-data.json on the data volume.

For larger setups, Redis persistence driver is highly recommended. See qtoggleserver.conf for details on how to configure the persistence driver. If in doubt, use docker compose to run the qToggleServer service along with a Redis service.

Versions

Available versions correspond to Docker image tags. For example, if you want to run version 0.28.4 instead of the current stable version, use:

$ docker run -it --rm -p 8888:8888 \
             -v /path/on/host/qtoggleserver-data:/data \
             -e TZ=Europe/Berlin \
             qtoggle/qtoggleserver:0.28.4

The stable tag always corresponds to the current (most recent) stable version, while latest represents the latest release, including beta versions.

Detached Mode

When you're with the configuration and you're happy with the way qToggleServer container runs, you should remove -it and --rm command-line switches from the run command so that the container starts in detached (background) mode. It is a good idea to give the container a specific name, for later reference:

$ docker run -d --name=qtoggleserver -p 8888:8888 \
             -v /path/on/host/qtoggleserver-data:/data \
             -e TZ=Europe/Berlin \
             qtoggle/qtoggleserver:stable

If you want to stop it (gracefully, using SIGTERM), just run:

$ docker kill -s TERM qtoggleserver

Installing Add-ons

To install Add-ons or other Python packages, or to run any other desired command, just start a new container with an interactive shell as command:

$ docker run -it --rm \
             -v /path/on/host/qtoggleserver-data:/data \
             qtoggle/qtoggleserver:stable \
             /bin/bash

You can now use pip to install Python packages. pip is actually a wrapper around uv pip, as uv is internally used by the container to manage packages and their dependencies. Your packages will be installed in the already activated virtual environment which lives on the data volume:

# pip install <package>

Don't forget to restart the qToggleServer main container.

If you need some dependencies to be installed before the server starts, such as a list of add-ons or any other kind of Python packages, you can place a requirements.txt file in the root of the data folder. It will be used once to install all packages listed in it and will be removed afterwards.

Using docker compose

Simple Example

A simpe docker-compose.yml file would look something like:

docker-compose.yml:

services:
  qtoggleserver:
    image: qtoggle/qtoggleserver:stable
    ports:
      - "8888:8888"
    volumes:
      - /path/to/host/qtoggleserver-data:/data
    environment:
      - TZ=Europe/Berlin

Running docker compose

To start docker compose, just run the following command in the folder where your docker-compose.yml lives:

$ docker compose up

This will start it in foreground. You can terminate it with Ctrl+C. Add the -d option to start it in detached (background) mode:

$ docker compose up -d

You can terminate it by running:

$ docker compose down

Redis

Adding a redis service is usually a good idea. Make sure you have set the Redis persistence driver in your qtoggleserver.conf file and that the host driver parameter is set to redis.

Then you can add the redis service to your docker-compose.yml:

docker-compose.yml:

services:
  qtoggleserver:
    image: qtoggle/qtoggleserver:stable
    ports:
      - "8888:8888"
    volumes:
      - /path/to/host/qtoggleserver-data:/data
    environment:
      - TZ=Europe/Berlin
  redis:
    image: redis:alpine
    volumes:
      - /path/to/host/qtoggleserver-data/redis:/data

Upgrading To New Version

Upgrading to a new version should be seamless: just change the desired version tag in your docker-compose.yml or in your commandline. Restarting the compose project will ensure you run your desired version of qToggleServer.

If you upgrade to a version that's built on top of a different Python interpreter version (e.g. from 3.10 to 3.11), the virtualenv that's used to run qToggleServer and that lives in your data directory will be recreated. A reinstall of all previous packages into the new virtualenv will be attempted.

The /path/to/host/qtoggleserver-data/user directory (the one that's mounted at /data/user inside the container) is guaranteed to be preserved across any kind of updates; you can safely place any custom scripts or files you need for a proper functioning of your qToggleServer setup.