Docker Compose

The canonical way to deploy Weavestream is with the published compose.yml. This guide covers a production-grade setup.

The compose.yml

The compose file defines five services:

services:
  postgres:   # PostgreSQL 16 — primary database
  redis:      # Redis 7 — sessions, queues, cache
  api:        # NestJS REST API
  web:        # Next.js frontend
  worker:     # BullMQ background jobs

Uploaded files (attachments, thumbnails, logos, export PDFs) live on a host bind-mounted directory (${DATA_DIR}/files) shared by api and worker. No additional storage container is required.

All Weavestream images are pulled from GitHub Container Registry:

ghcr.io/weavestream/weavestream-{api,web,worker}:<version>

Production Setup

1. Download compose.yml and .env

Pin to a specific release tag:

mkdir weavestream && cd weavestream
curl -O https://raw.githubusercontent.com/Weavestream/Weavestream/v1.1.1/compose.yml
curl -O https://raw.githubusercontent.com/Weavestream/Weavestream/v1.1.1/.env.example
mv .env.example .env

2. Generate secrets

curl -O https://raw.githubusercontent.com/Weavestream/Weavestream/v1.1.1/scripts/keygen.sh
chmod +x keygen.sh
./keygen.sh >> .env

Update DATABASE_URL and REDIS_URL to use the newly generated passwords.

3. Set critical variables in .env

WEAVESTREAM_VERSION=1.1.1
APP_URL=https://your-domain.com
API_URL=https://your-domain.com/api
DATA_DIR=/opt/weavestream/data   # or your preferred path

4. Configure data directory

mkdir -p /opt/weavestream/data/{postgres,redis,files}

Or let Docker create it automatically on first boot.

5. Start the stack

docker compose up -d

6. Create the first admin

docker compose exec api node dist/cli.js create-admin

Health Checks

Each service has a health check defined in compose.yml. Check the status:

docker compose ps

The web and worker services wait for api to be healthy before starting. The api service runs prisma migrate deploy on boot — this takes a few seconds on first run.

Useful Commands

# View logs
docker compose logs -f api
docker compose logs -f worker

# Check API health
curl http://localhost:3000/api/health

# Run CLI commands
docker compose exec api node dist/cli.js --help

# Restart a single service
docker compose restart api

# Stop everything
docker compose down

# Stop and remove volumes (destructive — data loss!)
docker compose down -v

Scaling

api and worker are stateless and can be scaled horizontally:

docker compose up -d --scale api=3 --scale worker=2

prisma migrate deploy uses a Postgres advisory lock, so multiple api replicas are safe to start simultaneously.

Environment Variables at Runtime

Environment variables in .env are loaded by Docker Compose and injected into each container. To apply a change:

# Edit .env
docker compose up -d   # containers restart with new env

Some changes (like DATA_DIR) require the stack to be stopped first to avoid data loss.