Olaf
b428721b07
- 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>
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. Always run `./scripts/monitor-sso-health.sh` before and after changes
|
|
2. Backup first: `./scripts/backup-sso-infrastructure.sh`
|
|
3. Never modify network routing rules without verifying LAN/WAN access preserved
|
|
4. Docker compose changes require `sudo docker compose up -d` to apply
|