Docker Compose

Deploy Stib with Docker Compose for a production-ready, declarative setup. Define your entire configuration in a single compose.yaml file and manage Stib with simple docker compose commands — easy to maintain and fully reproducible.

TIP

Looking for a simpler single-container setup? See the Docker guide to run Stib with a single docker run command.

Prerequisites

• Docker Engine 20+ with the Compose plugin (or Docker Desktop which includes Compose)
• A terminal with network access to Docker Hub

Configuration

Create a compose.yaml file in your project directory:

Minimal

services:
  stib:
    image: enixion/stib-server:latest
    container_name: stib
    restart: unless-stopped
    ports:
      - "50505:50505"       # Web UI and API
    volumes:
      - stib-data:/app/data # Persistent data (database, logs, backups, attachments)
    environment:
      - RUST_LOG=info       # Logging level
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:50505/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  stib-data:

Full

services:
  stib:
    image: enixion/stib-server:latest
    container_name: stib
    restart: unless-stopped
    ports:
      - "50505:50505"       # Web UI and API
    volumes:
      - stib-data:/app/data # Persistent data (database, logs, backups, attachments)
    environment:
      - RUST_LOG=info                              # Logging level (info, debug, warn)
      - STIB_ENCRYPTION_KEY=your-hex-key-here      # Credential encryption (AES-256-GCM)
      - STIB_SERVER_ORIGIN=https://stib.example.com # Base URL for OIDC redirects
      - STIB_UPDATE_URL=https://your-update-endpoint # Update checker endpoint
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:50505/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  stib-data:

The examples above use curl for health checks. If your Docker image does not include curl, use wget instead:

curl

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:50505/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

wget

healthcheck:
  test: ["CMD", "wget", "--spider", "-q", "http://localhost:50505/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

Environment Variables

Variable	Description	Default	Required
STIB_ENCRYPTION_KEY	Credential encryption key (AES-256-GCM, hex-encoded 32 bytes)	—	Only if using encrypted credentials
STIB_SERVER_ORIGIN	Base URL for OIDC redirects (e.g., https://stib.example.com)	http://localhost:50505	Only for OIDC SSO
STIB_UPDATE_URL	Update checker endpoint	—	Optional
RUST_LOG	Logging level (info, debug, warn)	info	Optional

To generate a valid encryption key:

openssl rand -hex 32

Persistent Data

Stib stores all its data in /app/data inside the container. The named volume stib-data ensures data persists across container restarts and upgrades.

The data directory contains:

data/
├── stib.db          # SQLite database (auto-created)
├── logs/            # Rolling daily logs (7 files max)
├── backups/         # Database backups
└── attachments/     # Card attachments

Named volume (recommended)

volumes:
  - stib-data:/app/data

Bind mount

volumes:
  - ./stib-data:/app/data

WARNING

Always mount a volume for /app/data. Without it, your data is lost when the container is removed.

Running

Start Stib in detached mode:

docker compose up -d

View logs:

docker compose logs -f stib

Check container status:

docker compose ps

Stopping & Restarting

Stop the service (data is preserved in the volume):

docker compose down

Restart the service:

docker compose restart

Updating

Pull the latest image and recreate the container:

docker compose pull
docker compose up -d

TIP

Your data is safe — it lives in the stib-data volume, not in the container. Docker Compose automatically recreates only the containers whose image has changed. For extra safety, back up the database before updating:

docker compose cp stib:/app/data/stib.db ./stib.db.bak

Verify Installation

Check that Stib is running:

curl http://localhost:50505/api/health

Expected response:

{"data":{"status":"ok"}}

Then open http://localhost:50505 in your browser to access the web UI.

INFO

The Docker image is available for amd64 and arm64 architectures.

Customization

TIP

Common compose.yaml tweaks:

• Different port: Change "50505:50505" to "8080:50505" to expose Stib on port 8080
• Bind mount: Replace stib-data:/app/data with ./stib-data:/app/data to store data in a local directory
• Encryption: Add STIB_ENCRYPTION_KEY to enable credential encryption — generate a key with openssl rand -hex 32

Next Steps

TIP

Head to the Configuration guide to set up your admin account, configure OIDC authentication, and customize your instance.