Network Design

How node networking works. Every node uses the same network patterns - enclave networks for internal communication, direct networks for external access, and proxy networks for web services.

Network Types

Every node uses these four network types:

1. Enclave Networks

Internal, isolated networks with no internet access. Services talk to each other here.

2. Direct Networks

External connectivity for services that need internet access or exposed ports.

3. Proxy Networks

Connection to Traefik for web services that need external access.

4. Socket Networks

Secure Docker API access for management services only.

IP Address Allocation

Enclave Networks (`10.x.y.0/24`)

x = unique node identifier (0 for daedalus, 1 for icarus, 2 for helios)
y = service stack identifier (1 for root, 2+ for services)

Examples:

10.0.1.0/24 - daedalus root services
10.1.2.0/24 - icarus service stack 2
10.2.1.0/24 - helios root services

Direct Networks (`172.20.x.0/24` or macvlan)

VPS nodes use 172.20.x.0/24 ranges
Home nodes can use macvlan for LAN integration
x matches the service stack identifier

Network Definition Patterns

Enclave Network Setup

Standard internal network with no internet access:

1
2
3
4
5
6
7
networks:
  enclave:
    name: service-enclave
    internal: true          # Blocks internet access
    ipam:
      config:
        - subnet: 10.1.2.0/24

Services get predictable IPs:

1
2
3
4
5
6
7
8
9
services:
  app:
    networks:
      enclave:
        ipv4_address: 10.1.2.2
  database:
    networks:
      enclave:
        ipv4_address: 10.1.2.3

Direct Network Setup

External connectivity for services that need it:

1
2
3
4
5
6
networks:
  direct:
    name: service-direct
    ipam:
      config:
        - subnet: 172.20.2.0/24

Used for:

Port exposure (25565/tcp for game servers)
Internet access (download clients, API calls)
VPN endpoints

Proxy Network Setup

Connection to the node’s Traefik instance:

1
2
3
networks:
  root-proxy:
    external: true          # Created by root stack

Services connect here for web access:

1
2
3
4
5
6
7
services:
  webapp:
    networks:
      - enclave              # Internal communication
      - root-proxy          # External web access
    labels:
      - "traefik.http.routers.webapp.rule=Host(`app.domain.com`)"

Socket Network Setup

Secure Docker API access:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
networks:
  root-socket:
    external: true
    internal: true          # No internet access

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      SERVICES: 1
    networks:
      - root-socket

Management services connect here to manage containers safely.

Special Network Types

Macvlan Networks (Home Nodes)

For direct LAN integration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
networks:
  direct:
    driver: macvlan
    driver_opts:
      parent: eth0          # Host network interface
    ipam:
      config:
        - subnet: 192.168.1.0/24
          ip_range: 192.168.1.2/29    # Limited range
          gateway: 192.168.1.1

This puts containers directly on the LAN with their own IP addresses.

Service Communication Patterns

Same Service Stack

Services in the same stack use enclave network with service names:

1
2
3
# App connects to database
DATABASE_HOST: database
DATABASE_PORT: 5432

Cross-Stack Communication

Use direct IP addresses or external networks:

1
2
# Service A talks to Service B
BACKEND_URL: http://10.1.3.2:8080

External Web Access

Through Traefik with automatic HTTPS:

1
2
3
labels:
  - "traefik.http.routers.service.rule=Host(`service.domain.com`)"
  - "traefik.http.routers.service.tls.certresolver=cloudflare"

Network Security

Isolation

Enclave networks have internal: true - no internet
Services only connect to networks they need
Socket access restricted to management services

Firewall Integration

Direct networks work with host firewall rules:

1
2
3
# Example UFW rules for direct network
ufw allow from 172.20.0.0/16 to any port 22
ufw allow out on docker0

Docker API Security

Socket proxy limits what containers can do:

1
2
3
4
5
environment:
  CONTAINERS: 1         # Can manage containers
  IMAGES: 0            # Cannot pull/build images
  VOLUMES: 0           # Cannot create volumes
  NETWORKS: 0          # Cannot create networks

DNS Resolution

Internal Names

Services use Docker’s internal DNS:

Service names within same network
Container names as hostnames
Network aliases for custom names

External DNS

Configured through host or container DNS settings:

Pi-hole for filtering (if available)
Unbound for recursive resolution
Upstream DNS servers as fallback

Common Network Patterns

Web Service Stack

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
services:
  app:
    networks:
      - enclave           # Database communication
      - root-proxy       # Web access
  database:
    networks:
      - enclave          # Only internal access

networks:
  enclave:
    internal: true
  root-proxy:
    external: true

Backend Service with Internet

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
services:
  api:
    networks:
      - enclave          # Internal services
      - direct           # Internet access
  cache:
    networks:
      - enclave          # Only internal

networks:
  enclave:
    internal: true
  direct: {}

Management Service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
services:
  monitor:
    networks:
      - root-socket      # Docker API access
      - root-proxy       # Web dashboard

networks:
  root-socket:
    external: true
  root-proxy:
    external: true

This network design provides security through isolation while keeping setup simple and consistent across all nodes.

Last updated on October 2, 2025

System Overview Data Tiers