second-brain/05_Resources/Frusetik Access Architecture.md

Frusetik Access Architecture

Overview

Access architecture for frusetik.com. Public entry point is Cloudflare. Two targets behind the same Cloudflare Tunnel setup on the VPS: Pangolin / Traefik for app subdomains, and Authentik directly for auth.frusetik.com.

Critical gotchas that broke the setup during setup:

1. Pangolin internal TLS broke routing — must use HTTP internally
2. Immich iOS app breaks when Pangolin auth is enabled — must be "Not Protected"
3. cloudflared needed to be connected to authentik_default Docker network for auth.frusetik.com to work
4. Do NOT point Cloudflare web ingress at Gerbil for web app routing — Gerbil is part of Pangolin's tunnel system, not the normal HTTP routing target

---

Public hostnames

Hostname	Path
pangolin.frusetik.com	Cloudflare → Pangolin/Traefik on VPS
immich.frusetik.com	Cloudflare → Pangolin → home lab Immich
glance.frusetik.com	Cloudflare → Pangolin → home lab Glance
baersolar.frusetik.com	Cloudflare → Pangolin → home lab service
auth.frusetik.com	Cloudflare → Authentik directly on VPS (NOT Pangolin)

---

Architecture diagram

flowchart TD
    U[User / Browser / Mobile App] --> CF[Cloudflare Edge / DNS / Tunnel Routing]
    CF -->|auth.frusetik.com| CFL[cloudflared on VPS]
    CF -->|*.frusetik.com app routes| CFL
    subgraph VPS
        CFL -->|http| AK[Authentik]
        CFL -->|http| PT[Pangolin + Traefik]
        PT --> PG[Pangolin control / resource routing]
    end
    PG -->|Pangolin tunnel / connector| NW[Newt in home lab]
    subgraph Home Lab
        NW --> IM[Immich]
        NW --> GL[Glance]
        NW --> BS[Baersolar]
    end

---

Key design decisions

1. Cloudflare is the public entry point

Browser connects to Cloudflare over HTTPS. Cloudflare forwards through tunnel to VPS. Public TLS terminated at Cloudflare edge.

2. Pangolin and Authentik reached internally by HTTP

Internal TLS in Pangolin broke routing. Cloudflare already handles public HTTPS. Internal hop is HTTP on the VPS.

3. Authentik is NOT behind Pangolin

Authentik is routed directly to auth.frusetik.com. Pangolin is for app publishing only.

4. Immich must not be protected by Pangolin auth

iOS app breaks if Pangolin authentication is in front of Immich. Set to Not Protected in Pangolin.

---

Adding a new resource

Steps

1. Make available on home network — expose on some IP:PORT in the home lab
2. Create public resource in Pangolin — HTTP! If app access requires auth and supports OIDC, use Authentik as OpenID Provider; otherwise fall back to Pangolin's auth
3. Create Cloudflare Tunnel route — tunnel type HTTP, origin http://gerbil:80 (or https://gerbil:443 with NoTLSHandshake — untested)
4. Wire up Authentik — if app supports OIDC, add Authentik as OpenID Provider; else Pangolin auth handles it

---

Networking

Docker networks

• authentik_default — Authentik stack
• pangolin — Pangolin stack
• edge — future: shared network for cloudflared + public origins

Current network fix (temporary)

docker network connect authentik_default cloudflared

Required for cloudflared to reach Authentik by Docker DNS name.

Future cleanup

Create a shared edge network and attach cloudflared, Authentik server, and Pangolin/Traefik to it permanently.

---

Authentik access model

Groups

• family — trusted family members (Immich, Nextcloud access)
• movie-friends — limited access (Jellyfin only, no Immich)

Access matrix

Application	family	movie-friends
Immich	yes	no

Implementation

• One account per real person
• Application access controlled via Group bindings on the Application in Authentik
• If an application has no bindings, it may be accessible to all authenticated users — always bind explicitly

Note on Immich

Current live state: Immich in Pangolin = Not Protected (for iOS app compatibility). Authentik access policy is the desired target model, not the currently enforced gate on the mobile path.

---

Operational checklist

Pangolin resources stop working

1. Check whether TLS got re-enabled in Pangolin
2. Confirm resource still uses HTTP internally
3. Check resource hostname in Pangolin
4. Check whether auth was re-enabled for Immich
5. Confirm Pangolin/Traefik is still the Cloudflare tunnel target

auth.frusetik.com breaks

1. Check cloudflared is still connected to authentik_default: docker inspect cloudflared
2. Test connectivity: docker run --rm --network authentik_default curlimages/curl:8.6.0 curl -i http://server:9000
3. Check Cloudflare tunnel mapping for auth.frusetik.com

Immich mobile app breaks

1. Confirm immich-prod in Pangolin is still Not Protected
2. Confirm resource still uses HTTP inside Pangolin

---

Error Reference

Error	Cause	Fix
404 page not found on immich.frusetik.com	Pangolin internal TLS enabled	Disable TLS, enforce HTTP
too_many_redirects from http://gerbil:80	Wrong origin target	Use Pangolin/Traefik, not Gerbil directly
Cloudflare 502 on auth.frusetik.com	cloudflared can't resolve server hostname	docker network connect authentik_default cloudflared
Immich iOS app not working	Pangolin auth in front of Immich	Set Immich to Not Protected in Pangolin

---

Useful commands

# List Docker networks
docker network ls

# Inspect cloudflared networks
docker inspect cloudflared

# Inspect authentik network
docker network inspect authentik_default

# Test auth.frusetik.com from authentik network
docker run --rm --network authentik_default curlimages/curl:8.6.0 \
  curl -i -H "Host: auth.frusetik.com" http://server:9000