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>
This commit is contained in:
75
CLAUDE.md
Normal file
75
CLAUDE.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user