Docker (recommended)

The recommended way to deploy Tether. Docker Compose starts both the app and MariaDB with one command, handles networking between them, and ensures consistent behaviour across environments.

Prerequisites

• Docker Engine 24.0+ — Install Docker
• Docker Compose V2 — included with Docker Desktop; on Linux: apt install docker-compose-v2

Install

bashCopy
git clone https://github.com/atechlab-am/tether
cd tether

bashCopy
cp .env.example .env
nano .env

bashCopy
docker compose up -d

bashCopy
docker compose ps
# Both "tether-db" and "tether-app" should show status "Up"

docker compose logs -f app
# Watch for: "Application startup complete"

What gets started

The two containers communicate over an internal Docker network. MariaDB port 3306 is not exposed to the internet — only the Tether app container can reach it.

Volumes and data persistence

Tether uses two named Docker volumes to persist data across restarts and container rebuilds:

Useful commands

All commands must be run from the directory containing docker-compose.yml.

bashCopy
# Check container status
docker compose ps

# Stream app logs
docker compose logs -f app

# Stream database logs
docker compose logs -f db

# Stop containers (data preserved)
docker compose down

# Stop and DELETE all data (irreversible!)
docker compose down -v

# Restart just the app (after config change)
docker compose restart app

# Open a shell inside the app container
docker compose exec app bash

# Connect to MariaDB CLI
docker compose exec db mariadb -u tether -ptether tether

Updating Tether

Always back up your database before updating. See Backup & restore.

bashCopy
# 1. Pull the latest code
git pull

# 2. Stop just the app (keep the database running)
docker compose stop app

# 3. Rebuild the app image
docker compose build --no-cache app

# 4. Start the updated app
docker compose start app

# 5. Check logs to confirm startup
docker compose logs -f app

Schema changes (new tables, new columns) are applied automatically on startup by SQLAlchemy. Check the release notes for any version that requires a manual migration step.

Changing the port

By default Tether is exposed on port 8000. To change it, edit the ports section in docker-compose.yml:

yamlCopy
services:
  app:
    ports:
      - "80:8000"   # Now accessible on port 80

For production, use a reverse proxy on ports 80 and 443 instead of exposing Tether directly. See Reverse proxy & HTTPS.

Behind a reverse proxy

If you put nginx or Caddy in front of Tether, you must pass the real Host header through to the app — Tether uses this header to determine which tenant to scope requests to. A missing or incorrect Host header will break tenant routing.

nginxCopy
# Critical: pass Host header through
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

See the full nginx configuration in Reverse proxy & HTTPS.