silverbullet-notes/docs/01-network-architecture.md

Network Architecture

Last updated: 2025-12-13

This document describes the network architecture of the Docker-based application infrastructure.

Visual Diagram

[ Internet ]
      |
      |
[ Traefik Reverse Proxy @ 192.168.12.3 ]
      |
      --------------------------------------------------
      |                                                |
[ Server @ 192.168.1.252 ]                         [ Other Servers ]
      |                                                |
      ---[ traefik_proxy network ]---                   ---[ traefik_proxy network ]---
      |                                                |
[ Service Containers ]                             [ Service Containers ]

Docker Networks

The environment uses several Docker networks to isolate services and control traffic flow.

• traefik_proxy: This is the primary external network. All services that need to be exposed to the web via the Traefik reverse proxy are attached to this network. It is an "external" network, meaning it is created outside of any single docker-compose.yml file and is shared across multiple services.

• Service-specific networks: Some services create their own dedicated networks for communication between their internal components. Examples include:

  • calibre_network: For communication between the Calibre server and web UI.
  • weechat-network: For communication between the WeeChat relay and the Glowing Bear web client.

• default network: For services that are defined in the same docker-compose.yml file but are not exposed to the traefik_proxy network, they will communicate over a default bridge network created for that compose file.

Traefik Configuration

The main Traefik reverse proxy is running on a separate server at 192.168.12.3. Its configuration is managed via a dynamic configuration file named dyno.yml.

However, some services on this server (192.168.1.252) are also configured to be discovered by Traefik using Docker labels in their docker-compose.yml files. This is not the primary way of exposing services but is used for a select few.

• Entry Points: Traefik is configured with two main entry points:

  • web (port 80): Redirects all HTTP traffic to HTTPS.
  • websecure (port 443): Handles all HTTPS traffic.

• SSL/TLS: SSL certificates are automatically provisioned and renewed by Traefik using Let's Encrypt. The certresolver is named myresolver in the Traefik configuration.

• Middleware: Traefik uses middleware to provide additional functionality, most notably authentication via Authelia. The two main middleware chains are:

  • authelia-brewery: For services on the 3ddbrewery.com domain.
  • authelia-fails: For services on the fails.me domain.

IP Addressing and DNS

• Server IPs: The servers in this infrastructure have static IP addresses on the local network.

  • 192.168.1.252: This server, where the majority of the application containers are running.
  • 192.168.12.3: The server running the main Traefik reverse proxy.
  • Other servers exist for specific purposes (e.g., Home Assistant, UniFi Controller).

• DNS:

  • External DNS: The public domains (3ddbrewery.com, fails.me) are managed by an external DNS provider. DNS records point to the public IP address of the network, and the router forwards ports 80 and 443 to the Traefik server.
  • Local DNS: Some services might be accessed via local DNS names, but the primary access method for web services is through the public domains.

Port Mapping

• Traefik Ports: The Traefik server exposes ports 80 and 443 to the internet.
• Service Ports: Most services do not expose their ports directly to the host machine. Instead, they are attached to the traefik_proxy network, and Traefik routes traffic to them based on the domain name.
• Exposed Ports: Some services expose ports for direct access or for services that don't go through Traefik. For example, sftp exposes port 2222.

Security Boundaries

• External Access: The only services that are directly accessible from the internet are those that have a router configured in Traefik. All external web traffic is forced to use HTTPS.
• Internal Access: Services that are not on the traefik_proxy network are only accessible from within the Docker host or by other containers on the same Docker network.
• Authentication: Most web services are protected by Authelia, requiring users to authenticate before they can access the service.