Skip to main content

Getting Started

Complete guide to setting up RavenmaskOS from scratch.

Prerequisites​

Hardware Requirements​

ComponentMinimumRecommended
CPU4 cores8+ cores
RAM8GB24GB+
Storage100GB SSD500GB+ NVMe
BackupExternal driveSSD + Cloud

Software Requirements​

  • macOS (for Colima) or Linux with Docker
  • Homebrew (macOS)
  • Git
  • 1Password CLI with service account

Accounts Required​

ServicePurpose
AWSRoute 53 DNS management
1PasswordSecrets management
Backblaze B2Offsite backup
GitHubConfiguration sync

Initial Setup​

1. Install Dependencies (macOS)​

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Docker via Colima
brew install colima docker docker-compose

# Start Colima with resources
colima start --cpu 8 --memory 16 --disk 100

# Install backup tools
brew install restic

# Install pre-commit tools
brew install pre-commit gitleaks

2. Configure 1Password CLI​

# Download from https://1password.com/downloads/command-line/

# Configure service account
export OP_SERVICE_ACCOUNT_TOKEN="<your-token>"
echo 'export OP_SERVICE_ACCOUNT_TOKEN="<token>"' >> ~/.zshrc

# Verify access
op whoami
op vault list

3. Clone Repository​

cd ~
git clone git@github.com:nwalker85/ravenhelm.git
cd ravenhelm

# Install pre-commit hooks
pre-commit install

4. Generate Secrets​

Create the master secrets file from 1Password:

mkdir -p ~/ravenhelm/secrets
chmod 700 ~/ravenhelm/secrets

cat > ~/ravenhelm/secrets/.env << EOF
# AWS Route53
AWS_ACCESS_KEY_ID=$(op read "op://ravenmask/AWS Route53/username")
AWS_SECRET_ACCESS_KEY=$(op read "op://ravenmask/AWS Route53/credential")
AWS_HOSTED_ZONE_ID=$(op read "op://ravenmask/AWS Route53/hosted_zone_id")
AWS_REGION=us-east-1

# PostgreSQL
POSTGRES_USER=$(op read "op://ravenmask/PostgreSQL/username")
POSTGRES_PASSWORD=$(op read "op://ravenmask/PostgreSQL/password")
POSTGRES_DB=ravenhelm

# Redis
REDIS_PASSWORD=$(op read "op://ravenmask/Redis/password")

# Traefik
TRAEFIK_DASHBOARD_USER=$(op read "op://ravenmask/Traefik Dashboard/username")
TRAEFIK_DASHBOARD_HTPASSWD=$(op read "op://ravenmask/Traefik Dashboard/htpasswd")
EOF

chmod 600 ~/ravenhelm/secrets/.env

5. Create Docker Network​

docker network create ravenhelm_net

6. Create Data Directories​

mkdir -p ~/ravenhelm/data/{traefik,postgres,redis,grafana,loki,tempo}

Core Deployment​

Deploy services in this order to satisfy dependencies:

Layer 1: Reverse Proxy​

cd ~/ravenhelm/services/traefik
ln -sf ../../secrets/.env .env
docker compose up -d

# Verify
docker logs traefik | grep -i "configuration"
curl -I https://traefik.ravenhelm.dev

Layer 2: Data Stores​

# PostgreSQL
cd ~/ravenhelm/services/postgres
ln -sf ../../secrets/.env .env
docker compose up -d
docker exec postgres pg_isready

# Redis
cd ~/ravenhelm/services/docs/infrastructure/redis
ln -sf ../../secrets/.env .env
docker compose up -d
docker exec redis redis-cli -a $REDIS_PASSWORD ping

Layer 3: Identity​

# Zitadel SSO
cd ~/ravenhelm/services/zitadel
ln -sf ../../secrets/.env .env
docker compose up -d

# Wait for initialization (2-3 minutes)
docker logs -f zitadel

Layer 4: Observability​

for svc in prometheus loki tempo grafana alloy; do
  cd ~/ravenhelm/services/$svc
  ln -sf ../../secrets/.env .env
  docker compose up -d
done

Layer 5: Application Services​

for svc in n8n uptime-kuma homepage; do
  cd ~/ravenhelm/services/$svc
  ln -sf ../../secrets/.env .env
  docker compose up -d
done

Verification​

Check All Containers​

docker ps --format "table {{.Names}}\t{{.Status}}" | sort

Test Core Services​

# Traefik
curl -I https://traefik.ravenhelm.dev

# PostgreSQL
docker exec postgres pg_isready -U ravenhelm

# Redis
docker exec redis redis-cli -a $REDIS_PASSWORD ping

# Grafana
curl -I https://grafana.ravenhelm.dev

Verify DNS​

dig +short traefik.ravenhelm.dev
dig +short grafana.ravenhelm.dev

Configure Backup​

Local Backup (T9 SSD)​

mkdir -p ~/.config/restic

cat > ~/.config/restic/homelab.env << 'EOF'
export RESTIC_REPOSITORY="/Volumes/T9/restic-homelab"
export RESTIC_PASSWORD_COMMAND='op read "op://ravenmask/restic-homelab/password"'
EOF

# Initialize repository
source ~/.config/restic/homelab.env
restic init

Offsite Backup (B2)​

cat > ~/.config/restic/b2.env << 'EOF'
export RESTIC_REPOSITORY="b2:ravenhelm:ravenhelm-homelab"
export B2_ACCOUNT_ID=$(op read "op://ravenmask/backblaze ravenhelm api key/keyID")
export B2_ACCOUNT_KEY=$(op read "op://ravenmask/backblaze ravenhelm api key/credential")
export RESTIC_PASSWORD_COMMAND='op read "op://ravenmask/restic-homelab/password"'
EOF

# Initialize repository
source ~/.config/restic/b2.env
restic init

Schedule Backups​

# Add to crontab
crontab -e

# Daily local backup at 2:30 AM
30 2 * * * /Users/ravenhelm/ravenhelm/scripts/backup/backup-all.sh

# Weekly B2 sync at 3:30 AM Sunday
30 3 * * 0 /Users/ravenhelm/ravenhelm/scripts/backup/sync-b2.sh

Post-Setup Tasks​

  1. Configure Zitadel users - Create admin and service accounts
  2. Set up SSO - Connect Grafana, GitLab, n8n to Zitadel
  3. Import Grafana dashboards - Load monitoring dashboards
  4. Configure n8n workflows - Set up automation
  5. Test backup/restore - Verify disaster recovery works

Next Steps​