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 - stack definition
.env.example - environment variable template
nginx.conf - reverse proxy configuration
images.tar.gz - bundled Docker images (no internet access required)

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. Load Docker images

docker load -i images.tar.gz

This only needs to be run once per install.

3. Start the stack

docker compose up -d

4. Verify

# Check all containers are healthy
docker compose ps

# Test the API
curl https://orbisid.example.local/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. Load Docker images

docker load -i images.tar.gz

This only needs to be run once per install.

4. 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

Place your certificate files:

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

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

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
}

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

Your data is safe during upgrades

OrbisID stores all data in a named Docker volume (orbisid_postgres_data). Swapping Docker images never touches this volume — your database, scan history, accounts, credentials, and configuration are all preserved. The only command that destroys data is docker compose down -v, which explicitly removes volumes. Never use that flag when upgrading.

1. Back up

Before upgrading, create a database dump as a precaution:

# All-in-one: dump the database from the running container
docker compose exec postgres pg_dump -U orbisid orbisid > backup-$(date +%Y%m%d).sql

# External database: use your standard backup process

Also keep a copy of your .env file (it contains your ENCRYPTION_KEY, which cannot be recovered if lost).

2. Download and extract the new release package

Download the new version from the OrbisID website and extract it alongside your current installation:

tar -xzf orbisid-<new-version>-all-in-one.tar.gz
cd orbisid-<new-version>-all-in-one

3. Copy your existing `.env`

cp ../orbisid-<old-version>-all-in-one/.env .env

Update ORBISID_VERSION in .env to the new version:

ORBISID_VERSION=<new-version>

4. Load the new Docker images

docker load -i images.tar.gz

This replaces the application images in your local Docker engine. The PostgreSQL image (and its data volume) is not affected.

5. Restart the stack

Stop the old containers and start the new ones from the new directory:

# Stop the old stack (data volume is preserved)
docker compose -f ../orbisid-<old-version>-all-in-one/docker-compose.yml down

# Start the new stack
docker compose up -d

If you are upgrading in-place (same directory), a single command is enough:

docker compose up -d

Docker Compose detects that the image tags have changed and recreates only the affected containers. The postgres container is unchanged and its data volume is untouched.

Database migrations run automatically on startup. The backend applies any new Flyway migrations before accepting requests — you do not need to run SQL manually.

6. Verify

# Check all containers are healthy
docker compose ps

# Confirm the new version is running
curl http://orbisid.example.local/api/v1/version

Stopping and Removing

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

# Start again later — all data is intact
docker compose up -d

Irreversible data loss

docker compose down -v removes all Docker volumes including the PostgreSQL data volume. This permanently deletes your database. Only use it when you intend to wipe the installation completely. Never use it when upgrading.

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

Deployment Options​

All-in-One Deployment​

1. Extract and configure​

2. Load Docker images​

3. Start the stack​

4. Verify​

External Database Deployment​

1. Prepare the database​

2. Extract and configure​

3. Load Docker images​

4. Start the stack​

Enabling HTTPS​

Option A: Terminate TLS at Nginx​

Option B: Terminate TLS upstream​

Upgrading​

1. Back up​

2. Download and extract the new release package​

3. Copy your existing .env​

4. Load the new Docker images​

5. Restart the stack​

6. Verify​

Stopping and Removing​

Container Health Checks​

Logs​