Skip to content

Latest commit

 

History

History
171 lines (115 loc) · 4.89 KB

setup.md

File metadata and controls

171 lines (115 loc) · 4.89 KB

Setup

Getting started

The following steps describe how to set up the Quassel application system.

Environment

These steps describe how to set up the system environment on Ubuntu 24.04 LTS:

  1. Install updates

    apt update && apt upgrade

  2. Install Docker dependencies

    apt install apt-transport-https ca-certificates curl gnupg lsb-release

  3. Import Dockers GPG key

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

  4. Add Dockers apt repository

    • On x86_64

      echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

    • On ARM

      echo "deb [arch=arm64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

  5. Install Docker

    apt update && apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

  6. Validate the installation of Docker (>= 27.3.1)

    docker version

  7. Validate the installation of Docker Compose (>= 2.29.6)

    docker compose version

The following sources were used:

Application system

The following steps describe how to set up the application system:

  1. Copy the example files

    cd /srv \
&& wget https://raw.githubusercontent.com/openscript-ch/quassel/refs/heads/main/examples/public/docker-compose.yaml \
&& wget https://raw.githubusercontent.com/openscript-ch/quassel/refs/heads/main/examples/public/traefik.yaml \
&& wget https://raw.githubusercontent.com/openscript-ch/quassel/refs/heads/main/examples/public/.env.example

  2. Rename environment file and fill out the gaps mv .env.example .env

  3. Make sure that the DNS is routing all subdomains to the host where the individual services run on.

  4. Replace all example.com with the domain where the application runs on.

    sed -i "s/example.com/example.com/g" docker-compose.yaml

  5. Change contact email for SSL certificates in traefik.yaml

  6. Configure the following environment variables in docker-compose.yaml:

    • backend:
      • SESSION_SECRET to a 32byte random hex string with openssl rand -hex 32
      • SESSION_SALT to a 8byte random hex string with openssl rand -hex 8
      • DATABASE_PASSWORD set a more secure password for the database
    • frontend:

  7. Run application system

    docker compose -f docker-compose.yaml up -d

Automatic updates

For automatic updates, there is a watchtower service configured. This service exposes an endpoint at http://test.example.com:8080/v1/update. If a HTTP GET request is sent including the configured secret Bearer token to this endpoint, watchtower will pull new images and restart the services accordingly.

Monitoring

The following opinionated steps describe to push data to a Grafana instance via Prometheus:

  1. Get the remote url and token.

  2. Enable Docker Metrics.

    1. Add the following to the Docker daemon configuration file /etc/docker/daemon.json:

      {
  "metrics-addr" : "localhost:9323"
}

    2. Restart the Docker daemon with systemctl restart docker.

  3. Copy the Grafana Agent configuration example:

    wget https://raw.githubusercontent.com/openscript-ch/quassel/refs/heads/main/examples/public/grafana-agent.yaml

  4. Replace the remote_write url and token in grafana-agent.yaml.

    1. <endpoint> with the remote url.
    2. <token> with the token.

Tasks

The following sections describe the tasks to take care of the application system.

Release a new version

  1. Merge the release pull request and wait for completion of the pipeline.

Upgrade application system

  1. Pull new images

    docker compose -f docker-compose.yaml pull

  2. Recreate containers

    docker compose -f docker-compose.yaml up -d

  3. Migrate database

    docker exec -it $(docker ps -f name=backend -q) npx mikro-orm migration:up

  4. Seed database

    docker exec -it $(docker ps -f name=backend -q) npx mikro-orm seeder:run

Maintain application system

  • Create a database backup

    docker exec -it $(docker ps -f name=database -q) pg_dumpall -c -U postgres > quassel_dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql

  • Archive storage