01 - Architecture

• Global Architecture and Request Flow
• Network and Address Reference
• Storage Architecture

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:

Main Components

Core Infrastructure Roles

Proxmox VE

Proxmox VE hosts the Bytek VMs and LXCs.

Proxmox provides:

Proxmox management address:

Open Proxmox VE

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:

Pi-hole

Pi-hole provides:

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:

Authentik

Authentik is the central identity provider.

Authentik provides:

External Application Traffic

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

Nextcloud Example

A public Nextcloud request follows this path:

BookStack Example

A public BookStack request follows this path:

Vikunja Example

A public Vikunja request follows this path:

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.

An internal request follows this path:

This internal route provides:

Proxmox Private Access

Proxmox does not sit behind Traefik.

Pi-hole resolves:

The administrative path is:

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:

The authentication sequence is:

OIDC Callback Reference

Proxy Authentication

Some services do not support native OIDC.

Authentik Proxy Providers or ForwardAuth are used for:

Traefik Dashboard

The dashboard request follows this sequence:

Uptime Kuma

The Uptime Kuma request follows this sequence:

Standard User Access

The Authentik group bytek-users grants access to:

These applications also apply the Allow bytek.ca users policy.

Policy engine mode is set to ALL.

A user must therefore:

Administrator Access

The Authentik group bytek-admin grants access to:

Administrative applications also apply the Allow bytek.ca users policy.

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

Application Access Matrix

Service URLs

Break-Glass Access

Central authentication must not be the only recovery path.

Proxmox VE

Authentik

Nextcloud

BookStack

Uptime Kuma

Traefik

Pi-hole

Critical Dependencies

Failure Impact

Security Boundaries

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

Operational Principles

Document Control

Network and Address Reference

Purpose

This page documents the addressing, DNS, routing, and network-access model used by the Bytek homelab.

Use this page when:

Home Network

Service Address Inventory

Public Hostname Inventory

The public application records are managed through the WHC cPanel Zone Editor.

The public DNS destination is the VPS, not the private application address.

Private Hostname Inventory

All HTTPS application hostnames point internally to Traefik.

Proxmox is the exception because Proxmox does not sit behind Traefik.

Public DNS Flow

When an external client opens a hosted application:

Public DNS must never point directly to a private address such as 192.168.2.121.

Private RFC1918 addresses are not reachable from the public internet.

Internal Split-DNS Flow

When a client on the home LAN opens a hosted application:

This allows internal clients to use the same application hostnames and HTTPS certificates as external clients.

Benefits include:

Public and Private DNS Comparison

Proxmox DNS Design

The Proxmox host intentionally uses Quad9:

Proxmox does not use Pi-hole as its general resolver.

This design prevents the hypervisor from depending on a guest VM or LXC for DNS.

As a result, the Proxmox host normally resolves:

The Proxmox OIDC server-to-server path can therefore travel through:

If this public path causes a future OIDC reliability issue, a single entry may be added to the Proxmox /etc/hosts file:

This would route only Authentik directly through local Traefik while keeping general Proxmox DNS on Quad9.

Proxmox Private Hostname

The hostname pve.bytek.ca is intentionally private.

Pi-hole resolves it to:

No public WHC record should exist for pve.bytek.ca.

The Proxmox interface is accessed at:

Open Proxmox VE

Access should be limited to:

TCP port 8006 must not be exposed directly to the public internet.

Application Backend Reference

Traefik connects to each application using a private IP and backend port.

Backend ports should be accessible only from the systems that require them.

For example:

DHCP Reservations

Infrastructure services should use DHCP reservations based on their virtual NIC MAC addresses.

Known reservations include:

Additional infrastructure reservations should be confirmed in Pi-hole before being added to this page.

To locate a VM MAC address on Proxmox, use:

qm config <VMID>

Locate the net0 line and record the MAC address.

For an LXC, use:

pct config <CTID>

Reservations prevent unexpected address changes from breaking:

Firewall Source Reference

Known infrastructure sources include:

Typical firewall requirements include:

Avoid broad any-source rules when a specific infrastructure source can be used.

Browser Secure-DNS Warning

Firefox and Zen can use DNS over HTTPS and bypass Pi-hole.

This can cause private hostnames such as pve.bytek.ca to fail even when Pi-hole is configured correctly.

Recommended browser setting:

If an internal hostname fails only in the browser:

Useful Windows commands:

Expected result:

DNS Validation

Verify an Internal Record

Use:

nslookup portal.bytek.ca 192.168.2.65

Expected result:

Verify a Public Record Through Pi-hole

Use:

nslookup google.com 192.168.2.65

Expected result:

Verify Public WHC DNS

Query an authoritative WHC server and confirm that application hostnames resolve to:

Verify a Backend Port

Examples:

A successful connection confirms TCP reachability but does not prove the application is healthy.

Network Troubleshooting Order

When a hostname is unreachable, troubleshoot in this order:

Do not change DNS, firewalling, and application configuration simultaneously.

Address-Change Procedure

If a service IP changes:

A stale backend IP previously affected several deployment steps, so the old address should be searched across configuration files after every change.

Document Control

Storage Architecture

Purpose

This page documents the physical disks, Proxmox storage pools, logical-volume layout, filesystem mounts, and intended storage roles within the Bytek homelab.

The storage architecture separates:

The main design goal is to prevent application data, operating-system disks, and backups from competing for the same physical storage role.

Storage Overview

Physical Disk Inventory

Linux device names such as /dev/sda can change between boots or hardware changes.

Permanent references should use:

System NVMe

Physical Device

Partition Layout

Logical Volumes

Proxmox Storage

The pve-data thin pool appears in Proxmox as:

Intended Use

The system NVMe stores:

Current Workloads

The system NVMe currently stores operating-system disks for services such as:

Storage Policy

Use local-lvm for:

Avoid using local-lvm for:

User-Data NVMe

Physical Device

LVM-Thin Layout

The user-data NVMe contains:

These components represent:

Proxmox Storage

The thin pool appears in Proxmox as:

Intended Use

The user-data NVMe stores:

Current Major Workload

Nextcloud has a separate virtual data disk on user-data.

The Nextcloud operating system remains on local-lvm, while user files remain on user-data.

This separation makes it easier to:

Thin Provisioning

The local-lvm and user-data storage pools use LVM-thin provisioning.

A thin-provisioned virtual disk does not immediately consume its full nominal capacity.

For example, a 500 GB virtual disk initially consumes only the physical blocks that have actually been written.

Important Consequence

The sum of all nominal virtual-disk sizes may exceed the physical capacity of the thin pool.

This is safe only when actual usage is monitored.

If the thin pool reaches full physical allocation, affected VMs may experience:

Thin-Pool Monitoring

Review Proxmox storage usage using:

pvesm status

Review LVM-thin usage using:

lvs -a -o vg_name,lv_name,segtype,lv_attr,lv_size,data_percent,metadata_percent

Monitor both:

Suggested operational thresholds:

These thresholds are operational recommendations and should be adjusted based on growth rate and workload importance.

Backup HDD

Physical Device

Permanent Mount

The filesystem UUID is used instead of /dev/sda1 because Linux device letters can change.

Mount Options

The backup filesystem uses:

Mount-Point Protection

The Proxmox storage uses mount-point validation.

This prevents Proxmox from treating the empty directory /mnt/pve/pve-backup as valid storage when the HDD is not mounted.

Without this protection, a failed HDD mount could cause backups to be written to the Proxmox root filesystem.

That could fill the root filesystem and disrupt the hypervisor.

Backup-HDD Intended Use

The backup HDD stores:

The backup HDD must remain dedicated to backups.

Prohibited Backup-HDD Uses

Do not use the backup HDD for:

Mixing active workloads with backups would:

Storage Placement Rules

Future Plex Storage

The RTX 2060 Plex VM should not use the backup HDD for media.

Recommended placement:

A temporary media disk may be created on user-data for initial testing.

Long-term media storage should ideally use:

Media capacity planning must account for continued Nextcloud growth on user-data.

Future Game-Server Storage

A dedicated game-server VM should use:

Steam-installed server binaries can usually be downloaded again.

Unique game-world data, configuration files, allowlists, bans, and mods require backup.

Storage Expansion Principles

Before adding physical storage, decide whether the new disk is intended for:

Avoid adding unrelated physical disks into an existing unmirrored LVM volume group merely to increase capacity.

Safer future expansion patterns include:

Failure-Domain Considerations

System NVMe Failure

Expected impact:

Recovery would require:

User-Data NVMe Failure

Expected impact:

Backup HDD Failure

Expected impact:

Complete Host Failure

Expected impact:

This is the primary reason a future offsite or separate-host backup is required.

Snapshot Policy

Proxmox snapshots are used as short-term rollback points.

Recommended snapshot use cases:

Snapshots are not backups because:

Delete unnecessary snapshots after the associated change has been validated.

Avoid snapshots with RAM unless restoring the exact running state is required.

Storage Validation

Confirm Proxmox Storage

Use:

pvesm status

Expected storage IDs include:

Confirm Backup Mount

Use:

findmnt /mnt/pve/pve-backup

The source should be /dev/sda1.

Confirm Backup Capacity

Use:

df -h /mnt/pve/pve-backup

Confirm Physical Devices

Use:

lsblk -e7 -o NAME,PATH,SIZE,TYPE,FSTYPE,PTTYPE,MOUNTPOINTS,MODEL,SERIAL,WWN

Confirm Thin-Pool Utilization

Use:

lvs -a -o vg_name,lv_name,segtype,lv_attr,lv_size,data_percent,metadata_percent

Confirm Storage Configuration

Use:

cat /etc/pve/storage.cfg

Do not store credentials or secrets in the documentation when recording command output.

Disk-Health Monitoring

The backup HDD should be monitored using SMART.

Stable backup-HDD identifier:

/dev/disk/by-id/wwn-0x5000cca097c44d7e

Useful checks:

Important attributes include:

Pending or uncorrectable sectors require immediate review.

NVMe health should also be reviewed periodically using the appropriate NVMe SMART tools.

Capacity Review Checklist

Perform a storage review when:

Review:

Current Limitations

The current storage architecture does not provide disk redundancy.

The system NVMe, user-data NVMe, and backup HDD are independent single devices.

The architecture protects against some logical failures through backups, but does not provide uninterrupted operation after a physical disk failure.

The local backup HDD is in the same:

Future priorities include:

Document Control