Skip to main content

Deploy New Service

End-to-end guide for deploying a new Docker service to RavenmaskOS.

Overview​

Deploying a new service involves:

  1. Create service directory with docker-compose.yml
  2. Configure Traefik routing
  3. Link secrets
  4. Deploy and verify

Step-by-Step​

Step 1: Create Service Directory​

ssh ravenhelm@100.115.101.81

# Copy template
cp -r ~/ravenhelm/services/_template ~/ravenhelm/services/myservice

cd ~/ravenhelm/services/myservice

Step 2: Edit docker-compose.yml​

version: "3.9"

services:
  myservice:
    image: myimage:latest
    container_name: myservice
    restart: unless-stopped
    networks:
      - ravenhelm_net
    environment:
      - TZ=America/Chicago
      - DATABASE_URL=postgresql://ravenhelm:${POSTGRES_PASSWORD}@postgres:5432/ravenmaskos
    env_file:
      - .env
    volumes:
      - ../../data/myservice:/data
    labels:
      - "com.ravenhelm.service=myservice"
      - "traefik.enable=true"
      - "traefik.http.routers.myservice.rule=Host(`myservice.ravenhelm.dev`)"
      - "traefik.http.routers.myservice.entrypoints=websecure"
      - "traefik.http.routers.myservice.tls.certresolver=letsencrypt"
      - "traefik.http.services.myservice.loadbalancer.server.port=8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  ravenhelm_net:
    external: true
# Create symlink to central secrets
ln -s ../../secrets/.env .env

# Add service-specific secrets to central file if needed
echo "MYSERVICE_API_KEY=xxx" >> ~/ravenhelm/secrets/.env

Step 4: Create Data Directory​

mkdir -p ~/ravenhelm/data/myservice

Step 5: Deploy​

# Using deploy script
./scripts/deploy/deploy-service.sh myservice

# Or manually
cd ~/ravenhelm/services/myservice
docker-compose pull
docker-compose up -d

Step 6: Verify​

# Check container status
docker ps | grep myservice

# Check health
docker inspect myservice --format "{{.State.Health.Status}}"

# Check logs
docker logs myservice --tail=50

# Test HTTPS endpoint
curl -I https://myservice.ravenhelm.dev

Configuration Patterns​

With Authentication (OAuth2-Proxy)​

Add ForwardAuth middleware:

labels:
  - "traefik.http.routers.myservice.middlewares=oauth2-proxy@docker"

With Direct Zitadel SSO​

For apps that support OIDC directly:

environment:
  - OIDC_ISSUER=https://auth.ravenhelm.dev
  - OIDC_CLIENT_ID=xxx
  - OIDC_CLIENT_SECRET=${MYSERVICE_OIDC_SECRET}

Register the app in Zitadel first.

With Database​

environment:
  - DATABASE_URL=postgresql://ravenhelm:${POSTGRES_PASSWORD}@postgres:5432/myservice

Create database first:

docker exec -it postgres createdb -U ravenhelm myservice

With Redis​

environment:
  - REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0

DNS and TLS​

DNS is automatic via wildcard *.ravenhelm.dev. Traefik obtains TLS certificates automatically via Let's Encrypt.

# Verify DNS
dig myservice.ravenhelm.dev

# Check certificate
echo | openssl s_client -servername myservice.ravenhelm.dev \
  -connect myservice.ravenhelm.dev:443 2>/dev/null | \
  openssl x509 -noout -subject -dates

Rollback​

docker-compose down
rm -rf ~/ravenhelm/data/myservice
rm -rf ~/ravenhelm/services/myservice

Checklist​

  • Service directory created
  • docker-compose.yml configured
  • Secrets linked
  • Data directory created
  • Container running and healthy
  • HTTPS endpoint accessible
  • Authentication working (if applicable)
  • Logs flowing to Loki

See Also​

  • [[../DevOps/Container-Management]] - Docker patterns
  • [[../Infrastructure/Traefik]] - Routing details
  • [[../Identity-Management/OAuth2-Proxy]] - Authentication
  • [[Debug-Failing-Service]] - Troubleshooting