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

---

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

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

Using docker-compose

Simple Example

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

docker-compose.yml:

version: '3'
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:

version: '3'
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