Skip to main content
UpNext needs Redis and optionally PostgreSQL. Docker Compose is the easiest way to manage these services alongside the UpNext server.

​
Infrastructure services

Create a docker-compose.yml for your infrastructure:
docker-compose.yml
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3

  postgres:
    image: postgres:17-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: upnext
      POSTGRES_USER: upnext
      POSTGRES_PASSWORD: upnext
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U upnext -d upnext"]
      interval: 5s
      timeout: 3s
      retries: 3

volumes:
  redis_data:
  postgres_data:
Start the infrastructure: 
docker compose up -d
If you use UPNEXT_BACKEND=redis or UPNEXT_BACKEND=sqlite, you can skip the postgres service.

​
Start UpNext

Backend-first: set UPNEXT_BACKEND before upnext server start.
With infrastructure running, start the server and your services using the CLI:
1

Run database migrations (PostgreSQL backend only)

UPNEXT_BACKEND=postgres \
UPNEXT_DATABASE_URL=postgresql+asyncpg://upnext:upnext@localhost:5432/upnext \
upnext server db upgrade head
2

Start the dashboard server

UPNEXT_BACKEND=redis \
UPNEXT_WORKSPACE_ID=local \
UPNEXT_REDIS_URL=redis://localhost:6379 \
UPNEXT_AUTH_ENABLED=true \
UPNEXT_API_KEY=changeme \
upnext server start --port 8080
3

Start your worker and API

UPNEXT_WORKSPACE_ID=local \
UPNEXT_REDIS_URL=redis://localhost:6379 \
UPNEXT_URL=http://localhost:8080 \
UPNEXT_API_KEY=changeme \
upnext run service.py
The dashboard is available at http://localhost:8080 and your service connects to it automatically.
For self-hosted setups, UPNEXT_API_KEY is a single static bearer token.

​
Environment variables

VariableDescription
UPNEXT_BACKENDServer persistence backend: redis, sqlite, or postgres
UPNEXT_DATABASE_URLSQL connection URL used when UPNEXT_BACKEND=sqlite or postgres
UPNEXT_WORKSPACE_IDWorkspace namespace used by worker and API runtimes (local by default)
UPNEXT_REDIS_URLRedis connection URL
UPNEXT_AUTH_ENABLEDEnable the self-hosted bearer-token gate ("true" / "false")
UPNEXT_API_KEYStatic bearer token for self-hosted authentication
UPNEXT_ARTIFACT_STORAGE_BACKENDlocal or s3
See the full Configuration reference for all options.

​
Scale workers

To run multiple worker instances, use the replicas option in your Compose file or the --scale flag:
docker-compose.yml
services:
  worker:
    build: .
    command: upnext run service.py
    environment:
      UPNEXT_REDIS_URL: redis://redis:6379
    deploy:
      replicas: 3

# Or scale on the fly
docker compose up -d --scale worker=3
Each replica joins the same Redis Streams consumer group. Jobs are distributed automatically across all instances - no additional configuration required.

​
Volumes

VolumePurpose
redis_dataRedis AOF persistence
postgres_dataPostgreSQL data files