siriusscan--sirius/documentation/dev/deployment/README.docker-container-deployment.md

title, description, template, version, last_updated, author, tags, categories, difficulty, prerequisites, related_docs, dependencies, llm_context, search_keywords

title	description	template	version	last_updated	author	tags	categories	difficulty	prerequisites	related_docs	dependencies	llm_context	search_keywords
Docker Container Deployment Guide	Complete guide for deploying Sirius using prebuilt container images from GitHub Container Registry	TEMPLATE.guide	1.0.0	2026-04-08	Development Team	docker deployment containers ghcr registry production	deployment infrastructure	beginner	docker docker-compose	README.terraform-deployment.md README.development.md README.docker-architecture.md	docker-compose.yaml	high	docker deployment containers ghcr registry production images compose

Docker Container Deployment Guide

Purpose

This guide explains how to deploy Sirius using prebuilt container images from GitHub Container Registry (GHCR). This approach provides faster deployments (5-8 minutes vs 20-25 minutes) by eliminating on-instance Docker builds. The guide covers production deployments, image versioning, and fallback strategies.

When to Use

• Production deployments - Deploying Sirius to production environments
• Demo environments - Setting up demo instances quickly
• Staging environments - Creating isolated testing environments
• Quick deployments - When you need fast deployment without building from source
• CI/CD pipelines - Automated deployments using prebuilt images

Avoid when:

• Local development - Use docker-compose.dev.yaml for local builds with hot reloading
• Custom modifications - When you need to modify source code before deployment
• Offline environments - When registry access is unavailable

How to Use

Quick Start

# Clone repository
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius

# Generate startup config and secrets
docker compose -f docker-compose.installer.yaml run --rm sirius-installer

# Deploy with prebuilt images (default)
docker compose up -d

# Or specify a version tag
IMAGE_TAG=v0.4.1 docker compose up -d

# Optional: verify the public GHCR contract before pulling
bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}"

Prerequisites

• Docker >= 20.10.0
• Docker Compose >= 2.0.0
• Internet access to GitHub Container Registry (ghcr.io)
• Git (for cloning repository)

Container Registry Integration

GitHub Container Registry (GHCR)

Sirius images are automatically built and pushed to GitHub Container Registry on every push to the main branch. Images are available at:

• UI: ghcr.io/siriusscan/sirius-ui:{tag}
• API: ghcr.io/siriusscan/sirius-api:{tag}
• Engine: ghcr.io/siriusscan/sirius-engine:{tag}
• Postgres: ghcr.io/siriusscan/sirius-postgres:{tag}
• RabbitMQ: ghcr.io/siriusscan/sirius-rabbitmq:{tag}
• Valkey: ghcr.io/siriusscan/sirius-valkey:{tag}

docker-compose.yaml is the public-image deployment path for Sirius. If an unauthenticated docker pull against one of the image refs above returns unauthorized, the GHCR public-visibility contract is broken and operators should stop before rollout.

Image Tagging Strategy

Images are tagged with the following strategy:

Tag	Description	When Created
latest	Latest main branch build	On every push to main
beta	Beta release candidate	On main branch pushes
v0.4.1	Version-specific tag	After the Publish Release Image Tags workflow succeeds
dev	Development builds	On other branch pushes
pr-123	Pull request builds	On PR creation/updates

Image Availability

• Public images: No authentication required
• Multi-architecture: Images support linux/amd64 and linux/arm64
• Automatic updates: Latest images are built automatically by CI/CD
• Release contract: A release tag is only valid for operators after the release-tag workflow publishes it, the anonymous GHCR verification step passes, and the public Compose smoke test succeeds. CI validates latest on every main push (public-stack-contract in ci.yml); semver tags are additionally checked when a GitHub Release is published and on a weekly schedule (verify-ghcr-release-tag.yml).

Docker Compose Configuration

Base Configuration (Production)

The default docker-compose.yaml uses prebuilt images:

services:
  sirius-ui:
    image: ghcr.io/siriusscan/sirius-ui:${IMAGE_TAG:-latest}
    pull_policy: always
    # ... other configuration

  sirius-api:
    image: ghcr.io/siriusscan/sirius-api:${IMAGE_TAG:-latest}
    pull_policy: always
    # ... other configuration

  sirius-engine:
    image: ghcr.io/siriusscan/sirius-engine:${IMAGE_TAG:-latest}
    pull_policy: always
    # ... other configuration

Environment Variables

Control which images to use with the IMAGE_TAG environment variable:

# Use latest images (default)
docker compose up -d

# Use specific version
IMAGE_TAG=v0.4.1 docker compose up -d

# Use beta release
IMAGE_TAG=beta docker compose up -d

# Validate that the selected tag is publicly readable before rollout
bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}"

.env.production.example leaves IMAGE_TAG blank so fresh installer runs inherit the Compose default (latest). Pin a release tag only after the publish workflow has validated that all six Sirius images exist for that tag.

Development Override

For local development with source code changes, use the development override:

# Build locally with hot reloading
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build

The docker-compose.dev.yaml file overrides the registry images with local builds, enabling:

• Hot reloading
• Volume mounts for source code
• Development-specific environment variables
• Debug logging

Deployment Workflow

Standard Production Deployment

1. Clone repository:

   git clone https://github.com/SiriusScan/Sirius.git
   cd Sirius
   

2. Configure environment:

   docker compose -f docker-compose.installer.yaml run --rm sirius-installer
   # Optional: pass explicit values
   # docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
   

3. Deploy services:

   docker compose up -d
   

4. Verify deployment:

   docker compose ps
   docker compose logs -f
   

5. Check health:

   curl http://localhost:9001/health  # API
   curl http://localhost:3000/api/health  # UI
   

Maintainer Validation Path

Use the shared validation script to exercise the same public Compose path that operators use:

# Validate the default public stack (latest)
bash scripts/validate-public-compose-path.sh latest

# Validate a published release tag
bash scripts/validate-public-compose-path.sh v0.4.1

Version-Specific Deployment

Deploy a specific version:

# Set version tag
export IMAGE_TAG=v0.4.1

# Confirm the compose-rendered GHCR images are public and readable
bash scripts/verify-ghcr-public-access.sh "$IMAGE_TAG"

# Pull and start services
docker compose pull
docker compose up -d

Updating Deployment

To update to the latest version:

# Pull latest images
docker compose pull

# Restart services with new images
docker compose up -d

Fallback Strategy

When Registry is Unavailable

If GitHub Container Registry is unavailable or images fail to pull, you can fall back to local builds:

1. Use the committed source-build override:

   docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build
   

Note: Local builds take significantly longer (20-25 minutes vs 5-8 minutes) and require more system resources.

Secrets Hardening Overlays

For hardened deployments, Sirius includes optional overlay manifests:

• docker-compose.secrets.yaml for Compose secrets mounted at /run/secrets/*
• docker-stack.swarm.yaml for Swarm stack deployments

Example:

mkdir -p secrets
printf '%s' "your-postgres-password" > secrets/postgres_password.txt
printf '%s' "your-service-key" > secrets/sirius_api_key.txt
chmod 644 secrets/sirius_api_key.txt
printf '%s' "your-nextauth-secret" > secrets/nextauth_secret.txt
printf '%s' "your-admin-password" > secrets/initial_admin_password.txt

docker compose -f docker-compose.yaml -f docker-compose.secrets.yaml up -d

sirius_api_key.txt should stay world-readable (644) so bind-mounted /run/secrets/sirius_api_key is readable inside sirius-api / sirius-ui / sirius-engine (non-root UIDs).

Troubleshooting

Images Not Pulling

Problem: docker compose pull fails with authentication or network errors.

Solutions:

• Verify internet connectivity: curl -I https://ghcr.io
• Check image exists: Visit https://github.com/SiriusScan/Sirius/pkgs/container/sirius-ui
• Try pulling manually: docker pull ghcr.io/siriusscan/sirius-ui:latest
• Run the contract check: bash scripts/verify-ghcr-public-access.sh "${IMAGE_TAG:-latest}"
• If the script reports Anonymous access denied, the package is not publicly readable and the GHCR visibility workflow or token scope needs attention
• If the script reports Manifest missing, the requested tag was not published and you should verify the release-tag workflow completed successfully
• If the public Compose smoke test fails after pull succeeds, run bash scripts/validate-public-compose-path.sh "${IMAGE_TAG:-latest}" to reproduce the operator path and inspect the runtime contract failure
• Use fallback build strategy (see above)

Wrong Version Deployed

Problem: Services are running an unexpected version.

Solutions:

• Check current IMAGE_TAG: echo $IMAGE_TAG
• Verify image tags: docker compose images
• Pull specific version: IMAGE_TAG=v0.4.1 docker compose pull
• Restart services: docker compose up -d

Services Not Starting

Problem: Containers fail to start after pulling images.

Solutions:

• Check logs: docker compose logs
• Verify environment variables: docker compose config
• Check image compatibility: Ensure architecture matches (amd64/arm64)
• Verify dependencies: Ensure PostgreSQL, RabbitMQ, Valkey are running

Performance Issues

Problem: Deployment is slower than expected.

Solutions:

• Check network speed: docker pull should be fast on good connections
• Verify image sizes: Large images take longer to pull
• Use specific version tags instead of latest for faster pulls
• Consider using image caching strategies

Best Practices

Security

• Use specific version tags in production (e.g., v0.4.1) instead of latest
• Regularly update images to get security patches
• Scan images for vulnerabilities using Docker security scanning
• Use private registries for sensitive deployments (if needed)

Version Management

• Pin versions in production environments
• Test updates in staging before production
• Document versions deployed in each environment
• Use semantic versioning for releases

Performance

• Pre-pull images before deployment to reduce startup time
• Use image caching to avoid redundant pulls
• Monitor image sizes and optimize Dockerfiles if needed
• Use multi-stage builds to reduce final image sizes

Monitoring

• Track deployment times to measure improvements
• Monitor registry availability and fallback usage
• Log image versions deployed for audit trails
• Alert on deployment failures for quick response

Comparison: Registry vs Local Builds

Aspect	Registry Images	Local Builds
Deployment Time	5-8 minutes	20-25 minutes
Resource Usage	Low (pull only)	High (compilation)
Network Required	Yes (for pull)	No (after clone)
Customization	Limited	Full
CI/CD Integration	Automatic	Manual
Best For	Production, demos	Development, offline

Integration with CI/CD

GitHub Actions

Images are automatically built and pushed by GitHub Actions on:

• Push to main branch → latest and beta tags
• Manual Publish Release Image Tags run → version-specific tag (e.g., v0.4.1)
• Pull requests → pr-{number} tags

Deployment Automation

Example GitHub Actions workflow for deployment:

name: Deploy Sirius
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy with registry images
        run: |
          docker compose pull
          docker compose up -d

Related Documentation

• Terraform Deployment Guide - AWS deployment using Terraform
• Development Guide - Local development setup
• Docker Architecture Guide - Container architecture details

Support

For issues with container deployment:

1. Check the troubleshooting section above
2. Review Docker logs: docker compose logs
3. Verify image availability on GitHub Container Registry
4. Create an issue in the Sirius repository

---

This guide follows the Sirius Documentation Standard. For questions about documentation structure, see ABOUT.documentation.md.