Automation Stack Installation

This guide covers workflow automation and CI infrastructure used by RavenmaskOS.

Overview

Component	Purpose	Port	URL
n8n	Workflow automation and integrations	5678	n8n.ravenhelm.dev
GitLab Runner	CI runner for GitLab projects	-	-

Prerequisites

Before deploying the Automation Stack:

Prerequisites completed
Core Stack running (Traefik, Redis)
Identity Stack configured (SSO for n8n)
A GitLab instance (self-hosted or SaaS) available for runner registration

Directory Structure

mkdir -p ~/ravenhelm/services/{n8n,gitlab-runner}
mkdir -p ~/ravenhelm/data/{n8n,gitlab-runner}

Step 1: Configure n8n Environment

Create ~/ravenhelm/services/n8n/.env:

cat > ~/ravenhelm/services/n8n/.env << 'ENV'
N8N_ENCRYPTION_KEY=<generate-secure-random>
NOTION_API_KEY=<optional>
NOTION_TASKS_DATABASE_ID=<optional>
NOTION_PROJECTS_DATABASE_ID=<optional>
TODOIST_API_KEY=<optional>
SLACK_BOT_TOKEN=<optional>
SLACK_PM_CHANNEL_ID=<optional>
NORNS_API_KEY=<optional>
ENV

Step 2: Deploy n8n

Create ~/ravenhelm/services/n8n/docker-compose.yml:

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    networks:
      - ravenhelm_net
    env_file:
      - .env
    environment:
      - N8N_HOST=n8n.ravenhelm.dev
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.ravenhelm.dev/
      - GENERIC_TIMEZONE=America/Chicago
      - N8N_PROXY_HOPS=1
      # SSO auto-login via external hooks
      - EXTERNAL_HOOK_FILES=/home/node/.n8n/hooks.js
      - N8N_FORWARD_AUTH_HEADER=X-Auth-Request-Email
      # Encryption and integrations
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - NOTION_API_KEY=${NOTION_API_KEY}
      - NOTION_TASKS_DATABASE_ID=${NOTION_TASKS_DATABASE_ID}
      - NOTION_PROJECTS_DATABASE_ID=${NOTION_PROJECTS_DATABASE_ID}
      - TODOIST_API_KEY=${TODOIST_API_KEY}
      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
      - SLACK_PM_CHANNEL_ID=${SLACK_PM_CHANNEL_ID}
      - NORNS_API_KEY=${NORNS_API_KEY}
    volumes:
      - /Users/ravenhelm/ravenhelm:/ravenhelm:ro
      - /Users/ravenhelm/ravenhelm/data/n8n:/home/node/.n8n
    labels:
      - "traefik.enable=true"
      # Main UI - protected by Zitadel SSO
      - "traefik.http.routers.n8n.rule=Host(`n8n.ravenhelm.dev`)"
      - "traefik.http.routers.n8n.entrypoints=websecure"
      - "traefik.http.routers.n8n.tls.certresolver=letsencrypt"
      - "traefik.http.routers.n8n.middlewares=oauth2-proxy-auth@docker"
      - "traefik.http.routers.n8n.priority=1"
      - "traefik.http.services.n8n.loadbalancer.server.port=5678"
      # Webhooks - bypass SSO, use n8n's native auth
      - "traefik.http.routers.n8n-webhooks.rule=Host(`n8n.ravenhelm.dev`) && PathPrefix(`/webhook`)"
      - "traefik.http.routers.n8n-webhooks.entrypoints=websecure"
      - "traefik.http.routers.n8n-webhooks.tls.certresolver=letsencrypt"
      - "traefik.http.routers.n8n-webhooks.priority=10"
      - "traefik.http.routers.n8n-webhooks.service=n8n"
      # API - bypass SSO, use n8n's PAT auth
      - "traefik.http.routers.n8n-api.rule=Host(`n8n.ravenhelm.dev`) && PathPrefix(`/api`)"
      - "traefik.http.routers.n8n-api.entrypoints=websecure"
      - "traefik.http.routers.n8n-api.tls.certresolver=letsencrypt"
      - "traefik.http.routers.n8n-api.priority=10"
      - "traefik.http.routers.n8n-api.service=n8n"

networks:
  ravenhelm_net:
    external: true

Start n8n:

cd ~/ravenhelm/services/n8n
docker compose up -d

Step 3: Deploy GitLab Runner

Create ~/ravenhelm/services/gitlab-runner/docker-compose.yml:

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: unless-stopped
    networks:
      - ravenhelm_net
    environment:
      - TZ=America/Chicago
    volumes:
      - ../../data/gitlab-runner:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    labels:
      - "com.ravenhelm.service=gitlab-runner"

networks:
  ravenhelm_net:
    external: true

Start the runner:

cd ~/ravenhelm/services/gitlab-runner
docker compose up -d

docker exec -it gitlab-runner gitlab-runner register \
  --url https://gitlab.example.com \
  --registration-token <runner-token> \
  --executor docker \
  --docker-image alpine:latest

Verification

n8n UI: https://n8n.ravenhelm.dev
GitLab Runner: check docker logs gitlab-runner for successful registration

Overview​

Prerequisites​

Directory Structure​

Step 1: Configure n8n Environment​

Step 2: Deploy n8n​

Step 3: Deploy GitLab Runner​

Verification​