Skip to main content

RavenmaskOS Wiki

The RavenmaskOS wiki is the primary source of truth for all infrastructure, services, and operational documentation.

Access​

MethodURL
Web UIhttps://gitlab.ravenhelm.dev/ravenmask/ravenmaskos/-/wikis/home
Git Clonehttps://gitlab.ravenhelm.dev/ravenmask/ravenmaskos.wiki.git

Local Clone​

The wiki is cloned locally on odin for easy editing:

# Location on odin
/tmp/ravenmaskos.wiki

# Initial clone (if needed)
cd /tmp
git clone https://gitlab.ravenhelm.dev/ravenmask/ravenmaskos.wiki.git

Updating the Wiki​

From ravenmask (via SSH)​

# Get GitLab token
GITLAB_TOKEN=$(op item get "GitLab MCP PAT" --vault ravenmask --fields credential --reveal)

# Pull latest changes
ssh ravenhelm@100.115.101.81 "cd /tmp/ravenmaskos.wiki && git pull"

# Make your edits (via SSH or editor)
ssh ravenhelm@100.115.101.81 "cat > /tmp/ravenmaskos.wiki/path/to/file.md << 'EOF'
# Your content here
EOF"

# Commit and push
ssh ravenhelm@100.115.101.81 "cd /tmp/ravenmaskos.wiki && git add -A && git commit -m 'Update: description' && git push https://oauth2:${GITLAB_TOKEN}@gitlab.ravenhelm.dev/ravenmask/ravenmaskos.wiki.git main"

From odin directly​

cd /tmp/ravenmaskos.wiki
git pull

# Edit files
vim Operations/Service-Name.md

# Commit and push (requires token)
git add -A
git commit -m "Update: description"
git push https://oauth2:<TOKEN>@gitlab.ravenhelm.dev/ravenmask/ravenmaskos.wiki.git main

Wiki Structure​

ravenmaskos.wiki/
├── home.md                 # Landing page with navigation
├── Getting-Started/        # Setup and onboarding
├── Architecture/           # System design and decisions
├── Infrastructure/         # Core platform services
│   ├── Traefik.md
│   ├── PostgreSQL.md
│   ├── Redis.md
│   └── ...
├── Observability/          # Monitoring stack
│   ├── Prometheus.md
│   ├── Grafana.md
│   ├── Loki.md
│   └── Alerting.md
├── AI-ML-Platform/         # AI services
│   ├── Norns.md
│   ├── Langfuse.md
│   └── Ollama.md
├── Voice-Platform/         # Voice services
├── Automation/             # n8n, GitLab CI
├── Smart-Home/             # Home Assistant
├── Operations/             # Deployment, secrets, backups
│   ├── Deployment.md
│   ├── Secrets.md
│   ├── Backups.md
│   └── Wiki.md (this file)
├── Runbooks/               # Step-by-step procedures
├── Troubleshooting/        # Common issues
└── Reference/              # Ports, URLs, CLI commands

Documentation Guidelines​

When to Update​

  • New service: Create a dedicated page in the appropriate section
  • Configuration change: Update the relevant service page
  • Incident resolution: Add to Troubleshooting or Runbooks
  • Architecture decision: Document in Architecture/

Page Template​

# Service Name

Brief description of what the service does.

## Overview

| Property | Value |
|----------|-------|
| Container | `container-name` |
| Port | 8080 |
| URL | https://service.ravenhelm.dev |
| Compose File | `compose/service/docker-compose.yml` |

## Configuration

Key configuration details...

## Operations

### Starting/Stopping
\`\`\`bash
docker compose -f compose/service/docker-compose.yml up -d
\`\`\`

### Health Check
\`\`\`bash
curl https://service.ravenhelm.dev/health
\`\`\`

## Troubleshooting

Common issues and solutions...

## Related

- [Other Service](/section/other-servicemd)

Best Practices​

  1. Keep it current - Update docs when making changes
  2. Include examples - Show actual commands and outputs
  3. Link related pages - Cross-reference for discoverability
  4. Use tables - For quick-reference information
  5. Document the why - Not just what, but reasoning behind decisions