matt/echo6-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: infrastructure documentation

Browse source 
Includes:
- Hardware environment reference (Proxmox cluster, VMs, LXCs)
- Services inventory with current deployments
- Caddy & DNS configuration reference
- Runbooks for common deployment procedures

Recent additions:
- SearXNG deployment (utility CT 102, search.echo6.co)
- TOC conversion to Proxmox with cortex VM
- Syncthing sync between Contabo and cortex

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Matt Johnson 2026-02-06 21:27:29 +01:00
commit 880ff09c90
14 changed files with 1986 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

77
docs/software/authentik.md Normal file
View file

@ -0,0 +1,77 @@
# Authentik SSO Configuration
## Location
- **Server:** Contabo (5.189.158.149 / 100.64.0.6)
- **URL:** https://auth.echo6.co
- **Internal Port:** 9000
## API Access
API token stored in `/home/zvx/projects/.ref/credentials` as `AUTHENTIK_API_TOKEN`
## Flow UUIDs
Required for OAuth2 provider creation:
| Flow | UUID |
|------|------|
| Authorization (implicit) | `86051292-389f-4bd9-b0f9-53cd32f197fd` |
| Authorization (explicit) | `6f9f5c89-9f98-4776-9e0d-a72a8ad17963` |
| Invalidation | `ed861c0d-2c81-4c3d-819b-946a21c4296a` |
| Provider Invalidation | `1eb91626-19a3-4f45-b384-d699c6189197` |
## Create New API Token
```bash
ssh root@100.64.0.6 'docker exec authentik-server ak shell -c "
from authentik.core.models import Token, User
user = User.objects.get(username=\"akadmin\")
token, created = Token.objects.get_or_create(
identifier=\"token-name\",
user=user,
defaults={\"intent\": \"api\", \"expiring\": False}
)
print(token.key)
"'
```
## Quick OAuth2 Provider Creation
```bash
# Source credentials
source /home/zvx/projects/.ref/credentials
# Create provider
curl -s -X POST "https://auth.echo6.co/api/v3/providers/oauth2/" \
-H "Authorization: Bearer $AUTHENTIK_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "AppName",
"authorization_flow": "86051292-389f-4bd9-b0f9-53cd32f197fd",
"invalidation_flow": "ed861c0d-2c81-4c3d-819b-946a21c4296a",
"client_type": "confidential",
"client_id": "appname",
"redirect_uris": [{"matching_mode": "strict", "url": "https://app.echo6.co/callback"}],
"sub_mode": "user_username"
}'
# Create application (use pk from provider response)
curl -s -X POST "https://auth.echo6.co/api/v3/core/applications/" \
-H "Authorization: Bearer $AUTHENTIK_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "AppName",
"slug": "appname",
"provider": PROVIDER_PK,
"meta_launch_url": "https://app.echo6.co"
}'
```
## Common Redirect URI Patterns
| Application Type | Redirect URI Pattern |
|------------------|---------------------|
| Web app | `https://app.echo6.co/callback` |
| Web app (oauth) | `https://app.echo6.co/oauth/callback` |
| Caddy forward auth | `https://app.echo6.co/outpost.goauthentik.io/callback` |

162
docs/software/caddy.md Normal file
View file

@ -0,0 +1,162 @@
# Caddy & DNS Reference
## Contabo Caddy
**Config:** `/etc/caddy/Caddyfile` on Contabo (ssh root@100.64.0.1)
### Current Site Blocks
| Domain | Backend | Service |
|--------|---------|---------|
| auth.echo6.co | 127.0.0.1:9000 | Authentik SSO |
| forge.echo6.co | 127.0.0.1:3001 | Forgejo Git |
| mail.echo6.co | https://127.0.0.1:8443 | Mailcow (tls_insecure_skip_verify) |
| vpn.echo6.co | 127.0.0.1:8084 | Headscale |
| vpn.echo6.co/admin* | 127.0.0.1:3100 | Headplane |
| autodiscover.echo6.co | https://127.0.0.1:8443 | Mailcow autodiscover |
| autoconfig.echo6.co | https://127.0.0.1:8443 | Mailcow autoconfig |
| vault.echo6.co | 127.0.0.1:8086 | Vaultwarden |
| proxmox.echo6.co | https://100.64.0.6:8006 (via Tailscale) | Proxmox VE (data node) |
### Commands
```bash
ssh root@100.64.0.1
caddy validate --config /etc/caddy/Caddyfile
systemctl restart caddy # admin off, so reload won't work
journalctl -u caddy -f
```
---
## Utility Caddy (Home)
**Location:** CT 101 on utility Proxmox (192.168.1.101)
**Tailscale IP:** 100.64.0.8
**Config:** `/etc/caddy/Caddyfile` inside CT 101
**SSL Certs:** `/etc/caddy/certs/` (managed by acme.sh)
**Port forward:** Router 80/443 → 192.168.1.101
### Current Site Blocks
| Domain | Backend | Pattern | Service |
|--------|---------|---------|---------|
| mesh.echo6.co | 100.64.0.7:8080 | Tailscale | MeshMonitor |
| search.echo6.co | 100.64.0.15:8080 | Tailscale | SearXNG |
### Commands
```bash
ssh root@192.168.1.241 'pct exec 101 -- cat /etc/caddy/Caddyfile'
ssh root@192.168.1.241 'pct exec 101 -- systemctl reload caddy'
ssh root@192.168.1.241 'pct exec 101 -- journalctl -u caddy -f'
```
---
## dnsmasq (Tailscale Split DNS)
**Config:** `/etc/dnsmasq.d/tailscale-dns.conf` on Contabo
**Listens on:** 100.64.0.1:53
### Current Records
| Domain | Tailscale IP | Service |
|--------|-------------|---------|
| auth.echo6.co | 100.64.0.1 | Authentik |
| forge.echo6.co | 100.64.0.1 | Forgejo |
| mail.echo6.co | 100.64.0.1 | Mailcow |
| vpn.echo6.co | 100.64.0.1 | Headscale |
| vault.echo6.co | 100.64.0.1 | Vaultwarden |
| docs.echo6.co | 100.64.0.1 | Wiki.js |
| proxmox.echo6.co | 100.64.0.1 | Proxmox VE (via Caddy) |
| stream.echo6.co | *TBD* | PeerTube - needs host verification |
| notes.echo6.co | *TBD* | Obsidian LiveSync - needs host verification |
### Commands
```bash
ssh root@100.64.0.1
nano /etc/dnsmasq.d/tailscale-dns.conf
systemctl restart dnsmasq
dig +short forge.echo6.co @100.64.0.1 # Test
```
---
## GoDaddy DNS Records (echo6.co)
### Contabo Services → 5.189.158.149
| Subdomain | Service |
|-----------|---------|
| auth | Authentik SSO |
| forge | Forgejo Git |
| mail | Mailcow Email |
| vpn | Headscale VPN |
| vault | Vaultwarden |
### Home Services → 199.6.36.163
| Subdomain | Service |
|-----------|---------|
| @ | Main site |
| ai | Open WebUI |
| docs | Wiki.js |
| stream | PeerTube |
| notes | Obsidian LiveSync |
| jellyfin | Jellyfin |
| mesh | MeshMonitor |
| search | SearXNG |
### Email Records
| Type | Name | Value |
|------|------|-------|
| MX | @ | mail.echo6.co |
| CNAME | autoconfig | mail.echo6.co |
| CNAME | autodiscover | mail.echo6.co |
| TXT | @ | v=spf1 mx a:mail.echo6.co -all |
| TXT | _dmarc | v=DMARC1; p=quarantine |
| TXT | dkim._domainkey | (DKIM key) |
---
## Headscale Config
**Location:** `/opt/headscale/` on Contabo
**Data:** Named Docker volume `headscale_headscale-data`
**Config:** `/opt/headscale/config.yaml`
```yaml
dns:
base_domain: echo6.mesh
nameservers:
global:
- 1.1.1.1
oidc:
issuer: "https://auth.echo6.co/application/o/headscale/"
client_id: "headscale"
```
**Split DNS:** Configured via dnsmasq on Contabo.
**Headplane:** Deployed at `vpn.echo6.co/admin` - OIDC via Authentik. First login gets Owner.
---
## Port Map (Contabo)
| Service | Container Port | Host Binding | Public Domain |
|---------|---------------|--------------|---------------|
| Authentik | 9000 | 127.0.0.1:9000 | auth.echo6.co |
| Forgejo | 3000 | 127.0.0.1:3001 | forge.echo6.co |
| Headscale | 8080 | 127.0.0.1:8084 | vpn.echo6.co |
| Headplane | 3000 | 127.0.0.1:3100 | vpn.echo6.co/admin |
| Mailcow | 8443 | 127.0.0.1:8443 | mail.echo6.co |
| Vaultwarden | 80 | 127.0.0.1:8086 | vault.echo6.co |
| Vaultwarden WS | 3012 | 127.0.0.1:3012 | vault.echo6.co/notifications/hub |
---
*Last updated: 2026-02-06 — Added SearXNG (search.echo6.co) on utility CT 102*

64
docs/software/dns.md Normal file
View file

@ -0,0 +1,64 @@
# GoDaddy DNS Management
## Script Location
`~/bin/godaddy-dns.py`
## API Credentials
Stored in `/home/zvx/projects/.ref/credentials` as:
- `GODADDY_API_KEY`
- `GODADDY_API_SECRET`
## Key IPs for DNS Records
| Purpose | IP |
|---------|-----|
| External (home services) | `199.6.36.163` |
| Contabo Server | `5.189.158.149` |
## Managed Domains
arclightvanguard.com, echo6.co, echo6.org, happylittlellc.com, idahomesh.com, k7zvx.com, lpmesh.com, maliceinwonderland.org, matthewwayne.com, smugglersden.co, underdogs.cc
## Usage Examples
```bash
# List all domains
godaddy-dns.py list-domains
# List records for a domain
godaddy-dns.py list echo6.co
# Add A record
godaddy-dns.py add-a echo6.co www 199.6.36.163
# Add CNAME record
godaddy-dns.py add-cname echo6.co blog www.echo6.co
# Add MX record with priority
godaddy-dns.py add-mx echo6.co mail.echo6.co --priority=10
# Delete record
godaddy-dns.py delete echo6.co A www
# Configure MX for all domains
godaddy-dns.py setup-mail
```
## Common Patterns
### Point subdomain to home network
```bash
godaddy-dns.py add-a echo6.co newservice 199.6.36.163
```
### Point subdomain to Contabo
```bash
godaddy-dns.py add-a echo6.co auth 5.189.158.149
```
### Create CNAME alias
```bash
godaddy-dns.py add-cname echo6.co alias target.echo6.co
```