Deployment Guide

OrbisID ships as two release packages. Choose the one that matches your environment.

Deployment Options

Package	Use When
All-in-One	You want a self-contained deployment with a bundled PostgreSQL database
External Database	You have an existing managed PostgreSQL instance (AWS RDS, Azure Database, etc.)

Both packages contain:

• docker-compose.yml - container orchestration
• .env.example - environment variable template
• nginx.conf - reverse proxy configuration

All-in-One Deployment

This is the simplest option. PostgreSQL runs as a container alongside OrbisID.

1. Extract and configure

tar -xzf orbisid-<version>-all-in-one.tar.gz
cd orbisid-<version>-all-in-one
cp .env.example .env

Edit .env:

.env

# Image version (pre-filled by the release)
ORBISID_VERSION=<version>
ORBISID_REGISTRY=orbisid

# Generate with: openssl rand -base64 32
ENCRYPTION_KEY=<your-encryption-key>

# Bundled PostgreSQL
POSTGRES_DB=orbisid
POSTGRES_USER=orbisid
POSTGRES_PASSWORD=<strong-password>

# Spring profile
SPRING_PROFILES_ACTIVE=docker

2. Start the stack

docker compose up -d

3. Verify

# Check all containers are healthy
docker compose ps

# Test the API
curl http://localhost/api/v1/version

External Database Deployment

Use this when connecting to a managed PostgreSQL instance.

1. Prepare the database

Create a database and user on your PostgreSQL instance:

CREATE DATABASE orbisid;
CREATE USER orbisid WITH PASSWORD '<strong-password>';
GRANT ALL PRIVILEGES ON DATABASE orbisid TO orbisid;

OrbisID applies schema migrations automatically on startup via Flyway.

2. Extract and configure

tar -xzf orbisid-<version>-external-db.tar.gz
cd orbisid-<version>-external-db
cp .env.example .env

Edit .env:

.env

ORBISID_VERSION=<version>
ORBISID_REGISTRY=orbisid

# Generate with: openssl rand -base64 32
ENCRYPTION_KEY=<your-encryption-key>

# External PostgreSQL connection
DB_HOST=your-postgres-host.example.com
DB_PORT=5432
DB_NAME=orbisid
DB_USERNAME=orbisid
DB_PASSWORD=<database-password>

SPRING_PROFILES_ACTIVE=docker

3. Start the stack

docker compose up -d

Enabling HTTPS

For production deployments, TLS should be enabled. The nginx.conf included in the release package contains a commented-out HTTPS server block.

Option A: Terminate TLS at Nginx

1. Place your certificate files:

mkdir ssl
cp /path/to/fullchain.pem ssl/fullchain.pem
cp /path/to/privkey.pem ssl/privkey.pem

2. Edit docker-compose.yml to expose port 443 and mount certificates:

nginx:
  ports:
    - "80:80"
    - "443:443"
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro
    - ./ssl/fullchain.pem:/etc/nginx/ssl/fullchain.pem:ro
    - ./ssl/privkey.pem:/etc/nginx/ssl/privkey.pem:ro

3. Edit nginx.conf - uncomment the HTTPS server block and update server_name:

server {
    listen 443 ssl http2;
    server_name your.domain.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    ssl_protocols       TLSv1.2 TLSv1.3;
    # ... rest of configuration
}

4. Restart Nginx:

docker compose restart nginx

Option B: Terminate TLS upstream

If you are using a load balancer (AWS ALB, Azure Application Gateway) or a CDN (Cloudflare) that handles TLS, the Nginx container can remain HTTP-only. Ensure the load balancer forwards traffic to port 80 on the Docker host.

Upgrading

1. Back up

Before upgrading, back up your database and encryption key:

# All-in-one: dump the database from the container
docker compose exec postgres pg_dump -U orbisid orbisid > backup.sql

# External database: use your standard backup process

2. Update the version

Edit .env and set the new version:

ORBISID_VERSION=<new-version>

3. Pull and restart

docker compose pull
docker compose up -d

Database migrations run automatically on startup. The backend will apply any new Flyway migrations before accepting requests.

4. Verify

curl http://localhost/api/v1/version

Stopping and Removing

# Stop all containers (data is preserved in volumes)
docker compose down

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

Container Health Checks

All services include Docker health checks:

Service	Health Check	Interval
PostgreSQL	pg_isready	10s
Backend	GET /actuator/health	30s
Frontend	HTTP check on port 3000	30s

View health status with:

docker compose ps

Logs

# All services
docker compose logs -f

# Single service
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f nginx
docker compose logs -f postgres