Skip to main content

Runbook: Deploy New Service

Overview​

  • What: Deploy a new Docker service to RavenmaskOS
  • When: Adding new application or capability
  • Duration: 15-30 minutes

Prerequisites​

  • SSH access to odin
  • Docker permissions (ravenhelm user)
  • Service-specific configuration requirements

Procedure​

Step 1: Create Service Directory​

cd ~/ravenhelm/services
cp -r _template <service-name>
cd <service-name>

Step 2: Create Data Directory​

mkdir -p ../../data/<service-name>

Step 3: Edit docker-compose.yml​

Update:

  • image: - Correct image and tag
  • container_name: - Match service name
  • volumes: - Map data directory
  • labels: - Traefik routing
  • environment: - Service variables
ln -sf ../../secrets/.env .env

Step 5: Add New Secrets (if needed)​

# Generate secret
../../scripts/utils/generate-secret.sh 32

# Add to .env
nano ../../secrets/.env

Step 6: Deploy​

docker compose up -d

Step 7: Verify​

docker compose ps
docker compose logs -f

Verification​

# Container running
docker ps | grep <service-name>

# Traefik routing (if exposed)
curl -I https://<service-name>.ravenhelm.dev

Rollback​

docker compose down
rm -rf ../../data/<service-name>
cd .. && rm -rf <service-name>

Troubleshooting​

Container exits immediately​

Check logs:

docker compose logs

Traefik not routing​

  1. Verify labels in docker-compose.yml
  2. Check container is on ravenhelm_net
  3. Verify DNS resolves