Files

Olaf b428721b07 Initial commit: cleaned project structure

- Consolidated documentation from Ralph Loop iterations
- Archived 20+ outdated/superseded files to .archive/
- Kept essential docs: OIDC integration, mobile setup, quick start
- Added operational scripts for health monitoring and backup
- Research artifacts preserved in .tasks/artifacts/

Current state:
- 3 VPS sites (fry, proton, photon) ONLINE in Pangolin
- brn-home site pending for local services (Jellyfin, etc.)
- Mobile access configuration pending

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-21 06:15:04 +00:00

2.8 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains SSO infrastructure configuration and documentation for a self-hosted Pangolin + Authentik + Guacamole deployment on brn (10.50.0.74). It is NOT a code project - it's an infrastructure-as-documentation repository with shell scripts, configuration guides, and deployment artifacts.

Architecture

Three platforms deployed on brn (10.50.0.74):

Platform	URL	Purpose	Docker Path
Authentik	https://sso.obr.sh	Central OIDC identity provider	/srv/docker/authentik
Pangolin	https://tunnel.obr.sh	WireGuard tunnel manager + identity-aware proxy	/srv/docker/pangolin
Guacamole	https://remote.obr.sh/guacamole/	Clientless RDP gateway	/srv/docker/guacamole

Protected services (SSO integration targets):

Jellyfin (video.obnh.io) - Media server
OpenWebUI (ll.obr.sh) - AI chat interface
Transmission (tor.obnh.network) - Torrent client
Pi-hole (dns.obnh.io) - DNS/ad blocking
Gitea instances on fry.obr.sh and proton.obr.sh

Network constraints (CRITICAL - must preserve):

LAN: 10.50.0.0/24 via br0
WAN: 31.24.10.184/23 via enp131s0
NAT masquerade for LAN → WAN routing

Common Commands

# Health check all SSO platforms
./scripts/monitor-sso-health.sh

# Backup all SSO databases and configs
./scripts/backup-sso-infrastructure.sh

# View logs
cd /srv/docker/authentik && sudo docker compose logs -f
cd /srv/docker/pangolin && sudo docker compose logs -f
cd /srv/docker/guacamole && sudo docker compose logs -f

# Restart a service
cd /srv/docker/<service> && sudo docker compose restart

Key Files

Scripts:

scripts/monitor-sso-health.sh - Checks HTTP status, container health, network connectivity
scripts/backup-sso-infrastructure.sh - Backs up PostgreSQL databases and configs to /srv/backups/

Documentation:

ADD-OIDC-INTEGRATIONS.md - Complete OIDC provider setup guide (6 providers)
DEPLOYMENT-COMPLETE.md - Deployment summary and next steps
QUICK-START.md - 5-minute setup checklist

Research artifacts (read-only reference):

.tasks/artifacts/ - Platform research, architecture analysis

Deployment Notes

All Docker stacks use /srv/docker/<name>/ paths
Secrets stored in .env files (chmod 600)
Traefik handles TLS termination and routing
Configuration deployed via Ralph Loop (iterative automation)

When Making Changes

Always run ./scripts/monitor-sso-health.sh before and after changes
Backup first: ./scripts/backup-sso-infrastructure.sh
Never modify network routing rules without verifying LAN/WAN access preserved
Docker compose changes require sudo docker compose up -d to apply

2.8 KiB Raw Permalink Blame History