# Global Architecture and Request Flow

## Purpose

The Bytek homelab provides privately hosted identity, collaboration, documentation, monitoring, project-management, and infrastructure services.

The environment is hosted on Proxmox VE and follows these design principles:

<div id="bkmrk-one-major-service-pe" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- One major service per VM or LXC.
- Public services enter through a VPS instead of direct home-router port forwarding.
- WireGuard transports public traffic securely from the VPS to the home network.
- Traefik terminates HTTPS and routes requests according to the requested hostname.
- Authentik provides centralized authentication, multi-factor authentication, and application-access policies.
- Pi-hole provides LAN DNS, split DNS, and DHCP reservations.
- Data-bearing applications use a dedicated LVM-thin storage pool.
- Proxmox backups are stored on a separate internal HDD.
- Management interfaces remain accessible only from the LAN or a trusted VPN whenever practical.
- Critical services retain an authentication or console path that does not depend on Authentik.

</div>## Main Components

<div id="bkmrk-component-address-pr" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Component</th><th>Address</th><th>Primary Role</th></tr><tr><td>Public VPS</td><td>`38.29.213.101`</td><td>Public HTTPS entry point</td></tr><tr><td>WireGuard gateway</td><td>`192.168.2.64`</td><td>VPS-to-home tunnel gateway</td></tr><tr><td>Pi-hole</td><td>`192.168.2.65`</td><td>DNS, split DNS, and DHCP reservations</td></tr><tr><td>Nextcloud AIO</td><td>`192.168.2.100`</td><td>File storage and collaboration</td></tr><tr><td>Uptime Kuma</td><td>`192.168.2.115`</td><td>Service monitoring</td></tr><tr><td>Vikunja</td><td>`192.168.2.121`</td><td>Project and task management</td></tr><tr><td>Authentik</td><td>`192.168.2.162`</td><td>Identity, authorization, and MFA</td></tr><tr><td>Traefik</td><td>`192.168.2.182`</td><td>HTTPS reverse proxy</td></tr><tr><td>Proxmox VE</td><td>`192.168.2.254`</td><td>Hypervisor</td></tr><tr><td>BookStack</td><td>**Confirm current IP**</td><td>Infrastructure documentation</td></tr></tbody></table>

</div></div></div>## Core Infrastructure Roles

### Proxmox VE

Proxmox VE hosts the Bytek VMs and LXCs.

Proxmox provides:

<div id="bkmrk-virtual-machine-and-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Virtual-machine and container isolation.
- Virtual networking.
- Proxmox firewalling.
- LVM-thin storage.
- Scheduled backups.
- Short-term snapshots.
- VM and LXC restoration.
- Emergency console access.

</div>Proxmox management address:

<span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Proxmox VE](https://pve.bytek.ca:8006/)</span>

Proxmox is intended for LAN or trusted VPN access only.

### Public VPS

The VPS is the public entry point for applications hosted at home.

The VPS receives public HTTPS traffic at `38.29.213.101` and forwards permitted traffic through WireGuard.

The VPS prevents each home service from requiring its own public router port forwarding rule.

### WireGuard Gateway

The home WireGuard gateway connects the VPS tunnel to the home LAN.

The gateway performs:

<div id="bkmrk-wireguard-tunnel-ter" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- WireGuard tunnel termination.
- Controlled traffic forwarding.
- Firewall filtering.
- Network address translation where required.
- Delivery of public HTTPS traffic to Traefik.

</div>### Pi-hole

Pi-hole provides:

<div id="bkmrk-lan-dns.-dns-filteri" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- LAN DNS.
- DNS filtering.
- Split-DNS records.
- DHCP reservations.
- Internal application-name resolution.

</div>Pi-hole allows the same application hostname to work both inside and outside the home network.

### Traefik

Traefik is the central HTTPS reverse proxy.

Traefik provides:

<div id="bkmrk-https-termination.-l" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- HTTPS termination.
- Let’s Encrypt certificate management.
- Hostname-based application routing.
- Communication with private application backends.
- Authentik ForwardAuth for selected administrative services.
- Dashboard visibility into routers, services, and certificates.

</div>### Authentik

Authentik is the central identity provider.

Authentik provides:

<div id="bkmrk-central-user-account" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Central user accounts.
- Multi-factor authentication.
- OpenID Connect.
- Proxy Providers.
- ForwardAuth.
- Group-based authorization.
- Email-domain policies.
- Embedded outpost services.

</div>## External Application Traffic

When an external user opens an application, traffic moves through the following components:

<div id="bkmrk-the-user-enters-an-a" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The user enters an application hostname such as `cloud.bytek.ca`.
2. WHC public DNS resolves the hostname to the VPS at `38.29.213.101`.
3. The VPS accepts the HTTPS connection on TCP port 443.
4. The VPS forwards the traffic through the WireGuard tunnel.
5. The home WireGuard gateway receives the tunneled traffic.
6. The gateway forwards the request to Traefik at `192.168.2.182`.
7. Traefik examines the requested hostname.
8. Traefik forwards the request to the correct internal application.

</div>### Nextcloud Example

A public Nextcloud request follows this path:

<div id="bkmrk-the-browser-opens-cl" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The browser opens `cloud.bytek.ca`.
2. WHC DNS returns `38.29.213.101`.
3. The VPS receives the connection.
4. The VPS forwards the connection through WireGuard.
5. The home gateway forwards the request to Traefik.
6. Traefik forwards the request to Nextcloud at `192.168.2.100` on TCP port 11000.

</div>### BookStack Example

A public BookStack request follows this path:

<div id="bkmrk-the-browser-opens-do" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The browser opens `docs.bytek.ca`.
2. WHC DNS returns `38.29.213.101`.
3. The VPS receives the connection.
4. The VPS forwards the connection through WireGuard.
5. The home gateway forwards the request to Traefik.
6. Traefik forwards the request to the BookStack VM on TCP port 6875.

</div>### Vikunja Example

A public Vikunja request follows this path:

<div id="bkmrk-the-browser-opens-pr" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The browser opens `projects.bytek.ca`.
2. WHC DNS returns `38.29.213.101`.
3. The VPS receives the connection.
4. The VPS forwards the connection through WireGuard.
5. The home gateway forwards the request to Traefik.
6. Traefik forwards the request to Vikunja at `192.168.2.121` on TCP port 3456.

</div>## Internal Application Traffic

LAN devices do not need to leave the home network and return through the VPS.

Pi-hole resolves public application hostnames directly to Traefik.

<div id="bkmrk-hostname-internal-ad" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Hostname</th><th>Internal Address</th></tr><tr><td>`cloud.bytek.ca`</td><td>`192.168.2.182`</td></tr><tr><td>`docs.bytek.ca`</td><td>`192.168.2.182`</td></tr><tr><td>`portal.bytek.ca`</td><td>`192.168.2.182`</td></tr><tr><td>`projects.bytek.ca`</td><td>`192.168.2.182`</td></tr><tr><td>`proxy.bytek.ca`</td><td>`192.168.2.182`</td></tr><tr><td>`status.bytek.ca`</td><td>`192.168.2.182`</td></tr></tbody></table>

</div></div></div>An internal request follows this path:

<div id="bkmrk-the-lan-client-queri" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The LAN client queries Pi-hole.
2. Pi-hole returns `192.168.2.182`.
3. The client connects directly to Traefik.
4. Traefik routes the request to the private application backend.

</div>This internal route provides:

<div id="bkmrk-lower-latency.-no-un" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Lower latency.
- No unnecessary public internet path.
- No dependence on router hairpin NAT.
- The same HTTPS hostname inside and outside the home network.
- Valid Let’s Encrypt certificates for internal and external access.

</div>## Proxmox Private Access

Proxmox does not sit behind Traefik.

Pi-hole resolves:

<div id="bkmrk-pve.bytek.ca-to-192." style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `pve.bytek.ca` to `192.168.2.254`.

</div>The administrative path is:

<div id="bkmrk-the-administrative-w" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The administrative workstation queries Pi-hole.
2. Pi-hole returns `192.168.2.254`.
3. The workstation connects to Proxmox on TCP port 8006.

</div>The Proxmox host itself uses Quad9 at `9.9.9.9` rather than Pi-hole.

This prevents the hypervisor from depending on Pi-hole for its own DNS resolution.

## Native OIDC Authentication

The following services use native Authentik OpenID Connect:

<div id="bkmrk-nextcloud.-vikunja.-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Nextcloud.
- Vikunja.
- BookStack.
- Proxmox VE.

</div>The authentication sequence is:

<div id="bkmrk-the-application-redi" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The application redirects the browser to `portal.bytek.ca`.
2. Authentik requests credentials and MFA.
3. Authentik evaluates application group and policy bindings.
4. Authentik redirects the browser to the application callback.
5. The application validates the returned token.
6. The application creates or matches the local user.
7. The application applies its own internal permissions.

</div>## OIDC Callback Reference

<div id="bkmrk-application-callback" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Application</th><th>Callback</th></tr><tr><td>Nextcloud</td><td>`https://cloud.bytek.ca/apps/user_oidc/code`</td></tr><tr><td>Vikunja</td><td>`https://projects.bytek.ca/auth/openid/authentik`</td></tr><tr><td>BookStack</td><td>`https://docs.bytek.ca/oidc/callback`</td></tr><tr><td>Proxmox VE</td><td>`https://pve.bytek.ca:8006`</td></tr></tbody></table>

</div></div></div>## Proxy Authentication

Some services do not support native OIDC.

Authentik Proxy Providers or ForwardAuth are used for:

<div id="bkmrk-traefik-dashboard.-u" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Traefik dashboard.
- Uptime Kuma dashboard.

</div>### Traefik Dashboard

The dashboard request follows this sequence:

<div id="bkmrk-the-administrator-op" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The administrator opens `proxy.bytek.ca`.
2. Traefik invokes the Authentik ForwardAuth middleware.
3. The embedded Authentik outpost validates the user.
4. Authentik requires membership in `bytek-admin`.
5. The authenticated request returns to the Traefik dashboard.

</div>### Uptime Kuma

The Uptime Kuma request follows this sequence:

<div id="bkmrk-the-administrator-op-1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The administrator opens `status.bytek.ca`.
2. Traefik forwards the request to the Authentik embedded outpost.
3. Authentik validates the user and policies.
4. The outpost forwards the request to Uptime Kuma.
5. Selected public status-page paths may bypass authentication when intentionally configured.

</div>## Standard User Access

The Authentik group `bytek-users` grants access to:

<div id="bkmrk-nextcloud.-vikunja.--1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Nextcloud.
- Vikunja.
- BookStack.

</div>These applications also apply the `Allow bytek.ca users` policy.

Policy engine mode is set to `ALL`.

A user must therefore:

<div id="bkmrk-belong-to-bytek-user" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Belong to `bytek-users`.
- Pass the `Allow bytek.ca users` policy.

</div>## Administrator Access

The Authentik group `bytek-admin` grants access to:

<div id="bkmrk-proxmox-ve.-traefik-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Proxmox VE.
- Traefik dashboard.
- Uptime Kuma dashboard.

</div>Administrative applications also apply the `Allow bytek.ca users` policy.

An administrator may belong to both `bytek-admin` and `bytek-users`.

## Application Access Matrix

<div id="bkmrk-service-authenticati" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Service</th><th>Authentication</th><th>Intended Group</th></tr><tr><td>Nextcloud</td><td>Native Authentik OIDC</td><td>`bytek-users`</td></tr><tr><td>Vikunja</td><td>Native Authentik OIDC</td><td>`bytek-users`</td></tr><tr><td>BookStack</td><td>Native Authentik OIDC</td><td>`bytek-users`</td></tr><tr><td>Proxmox VE</td><td>Native Authentik OIDC</td><td>`bytek-admin`</td></tr><tr><td>Traefik dashboard</td><td>Authentik ForwardAuth</td><td>`bytek-admin`</td></tr><tr><td>Uptime Kuma dashboard</td><td>Authentik Proxy Provider</td><td>`bytek-admin`</td></tr><tr><td>Pi-hole</td><td>Local authentication</td><td>Administrators on LAN</td></tr><tr><td>Nextcloud AIO</td><td>AIO local authentication</td><td>Administrators on LAN</td></tr><tr><td>WireGuard gateway</td><td>SSH key authentication</td><td>Administrators</td></tr><tr><td>VPS</td><td>SSH key authentication</td><td>Administrators</td></tr></tbody></table>

</div></div></div>## Service URLs

<div id="bkmrk-service-url-access-s" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Service</th><th>URL</th><th>Access Scope</th></tr><tr><td>Authentik</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Authentik](https://portal.bytek.ca/)</span></td><td>Public through Traefik</td></tr><tr><td>Nextcloud</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Nextcloud](https://cloud.bytek.ca/)</span></td><td>Public through Traefik</td></tr><tr><td>Vikunja</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Vikunja](https://projects.bytek.ca/)</span></td><td>Public through Traefik</td></tr><tr><td>BookStack</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open BookStack](https://docs.bytek.ca/)</span></td><td>Public through Traefik</td></tr><tr><td>Uptime Kuma</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Uptime Kuma](https://status.bytek.ca/)</span></td><td>Authentik-protected</td></tr><tr><td>Traefik dashboard</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Traefik](https://proxy.bytek.ca/)</span></td><td>Administrators only</td></tr><tr><td>Proxmox VE</td><td><span class="___xxxjie0 f1w7gpdv f1gqqdtu" data-wra="1" style="opacity: 1; transition: opacity 500ms ease-out;">[Open Proxmox](https://pve.bytek.ca:8006/)</span></td><td>LAN or VPN only</td></tr><tr><td>Nextcloud AIO</td><td>`https://192.168.2.100:8080/`</td><td>LAN or VPN only</td></tr></tbody></table>

</div></div></div>## Break-Glass Access

Central authentication must not be the only recovery path.

### Proxmox VE

<div id="bkmrk-recovery-account%3A-ro" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery account:** `root@pam`
- **Access methods:** Private hostname, private IP, or Proxmox console

</div>### Authentik

<div id="bkmrk-recovery-account%3A-lo" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery account:** Local Authentik administrator
- **Access methods:** Public portal or direct private backend during recovery

</div>### Nextcloud

<div id="bkmrk-recovery-account%3A-lo-1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery account:** Local Nextcloud administrator
- **Recovery path:** `/login?direct=1`

</div>### BookStack

<div id="bkmrk-recovery-account%3A-de" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery account:** Dedicated local BookStack administrator
- **Recovery method:** Switch `AUTH_METHOD` from `oidc` to `standard`

</div>### Uptime Kuma

<div id="bkmrk-recovery-account%3A-or" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery account:** Original Kuma administrator
- **Recovery method:** Restore direct private access and re-enable local authentication

</div>### Traefik

<div id="bkmrk-recovery-method%3A-ssh" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery method:** SSH into the Traefik VM and restore a known-good dynamic configuration
- **Secondary authentication:** Retained Basic Auth while ForwardAuth is being validated

</div>### Pi-hole

<div id="bkmrk-recovery-method%3A-pri" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Recovery method:** Private IP, local credentials, and Proxmox console

</div>## Critical Dependencies

<div id="bkmrk-function-dependency-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Function</th><th>Dependency Chain</th></tr><tr><td>Public applications</td><td>WHC DNS, VPS, WireGuard, Traefik, application</td></tr><tr><td>Internal applications</td><td>Pi-hole, Traefik, application</td></tr><tr><td>OIDC login</td><td>Application, Traefik, Authentik, Authentik database</td></tr><tr><td>Certificate issuance</td><td>Traefik, DNS, Let’s Encrypt, WHC cPanel API</td></tr><tr><td>Monitoring</td><td>Uptime Kuma, Pi-hole, monitored services</td></tr><tr><td>Backups</td><td>Proxmox, mounted backup HDD</td></tr></tbody></table>

</div></div></div>## Failure Impact

<div id="bkmrk-failed-component-exp" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Failed Component</th><th>Expected Impact</th></tr><tr><td>Pi-hole</td><td>Internal hostname resolution may fail</td></tr><tr><td>VPS</td><td>External access fails; LAN access should continue</td></tr><tr><td>WireGuard</td><td>External VPS ingress fails</td></tr><tr><td>Traefik</td><td>HTTPS routing fails</td></tr><tr><td>Authentik</td><td>New SSO logins fail</td></tr><tr><td>Proxmox</td><td>VM management fails; running guests may continue</td></tr><tr><td>Backup HDD</td><td>New backups fail; live services continue</td></tr><tr><td>Nextcloud</td><td>File and collaboration services fail</td></tr><tr><td>Vikunja</td><td>Project-management service fails</td></tr><tr><td>BookStack</td><td>Documentation service fails</td></tr><tr><td>Uptime Kuma</td><td>Monitoring and alerts fail</td></tr></tbody></table>

</div></div></div>## Security Boundaries

The following services must not be exposed directly to the public internet:

<div id="bkmrk-proxmox-tcp-8006.-pi" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Proxmox TCP 8006.
- Pi-hole administration.
- Nextcloud AIO TCP 8080.
- Nextcloud AIO backend TCP 11000.
- Authentik backend TCP 9000.
- Uptime Kuma backend TCP 3001.
- Vikunja backend TCP 3456.
- BookStack backend TCP 6875.
- Traefik internal dashboard service.
- SSH on home service VMs.
- Docker socket or Docker API.

</div>## Operational Principles

<div id="bkmrk-validate-the-direct-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Validate the direct application backend before troubleshooting Traefik.
2. Validate Traefik locally before troubleshooting the VPS.
3. Validate Pi-hole before changing application OIDC settings.
4. Confirm container DNS after a power failure.
5. Preserve local recovery accounts.
6. Do not regenerate OIDC secrets until connectivity is proven.
7. Do not delete Traefik certificate storage during troubleshooting.
8. Do not treat snapshots as backups.
9. Test restored VMs with their network adapter disconnected.
10. Update documentation after each validated infrastructure change.

</div>## Document Control

<div id="bkmrk-owner%3A-bryan-gagne-p" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Owner:** Bryan Gagne-Plante
- **Last verified:** YYYY-MM-DD
- **Backup coverage:** Partial
- **Recovery tested:** Partial
- **Offsite backup:** Not configured
- **Known limitations:** One Proxmox host and one local backup location

</div>