Homelab / Network & naming
V0.1 · Architecture & service documentation

HOW A REQUEST FINDS ITS SERVICE

Names, boundaries
and application routes.

The network has several responsibilities: connect systems, separate different uses, resolve names and deliver requests to the right application. Different tools own each part.

The responsibilities.

OPNsenseRouting and firewall policy between network roles.→UniFi ControllerManagement of supported network equipment.→BIND9Authoritative records for names managed inside the lab.→AdGuard HomeDNS filtering and selected resolver statistics.→TraefikHTTP routing and the common HTTPS entry layer.→phpIPAMAddress-space documentation, distinct from enforcement.→

Follow a web request.

Simplified web-request pathSimplified flow
  1. STEP 01Resolve the name
  2. STEP 02Reach the HTTPS entry
  3. STEP 03Match the Traefik route
  4. STEP 04Contact the application

DNS answers a naming question; it does not decide which application should handle an HTTP request. Traefik uses the request to select a backend. The application may then depend on a database, file storage or another service.

This conceptual flow does not prescribe a private routing path or an upstream chain between BIND9 and AdGuard. The latter have different documented roles, and their presence alone is insufficient to infer the resolver configuration of every client.

Separate environments by purpose.

The private network distinguishes management, production services, testing and connected-device roles. The purpose is to control which kinds of traffic can cross those boundaries and reduce accidental coupling between experiments and operational services.

Virtual network interfaces and guest placement are implementation details. The public diagrams omit subnet numbers, VLAN identifiers, gateway addresses, routes and firewall rules. The useful explanation here is why the boundaries exist, not an access map.

Adding a named web service.

  1. Define the application and confirm its backend behaviour in the intended environment.
  2. Add or update the relevant name through the reviewed DNS configuration.
  3. Configure the reverse-proxy router and backend service. Preserve the intended authentication boundary.
  4. Validate HTTPS, application identity, redirects and any longer-lived requests.
  5. Add the required Zabbix check and confirm its presence in the dynamic views.

These are separate checks even if one change includes several of them. A correct DNS record can still point to a proxy with a bad route, and a correct proxy can still reach an unhealthy application.

A neutral proxy example.

This is a structural illustration of a file-provider route, not an export from the lab. Certificate, entry-point and access settings must be supplied by the actual deployment.

ILLUSTRATIVE CONFIGURATION neutral names
http:
  routers:
    example-notes:
      rule: Host(`notes.example.com`)
      service: example-notes
      tls: {}
  services:
    example-notes:
      loadBalancer:
        servers:
          - url: http://example-notes:8080

Debug the layer that failed.

If a name is wrong, inspect naming before restarting an application. If the certificate or application identity is wrong, inspect the entry layer and routing. If the frontend works but an operation fails, follow the database, storage and worker dependencies.

The lab has encountered URLs returning a successful response from the wrong application. That is why the monitoring approach includes identity as well as status and latency.