Architecture
System Overview

System Overview

What makes a node and how they’re built. All nodes follow the same basic patterns - they’re just Docker hosts with standardized setup, networking, and data management.

What’s a Node?

A node is basically a Linux host running Docker services. Every node has the same fundamental structure:

  • Docker Compose stacks - Services organized by function
  • Standardized networking - Consistent IP ranges and network types
  • Data tier system - @tier1, @tier2, @tier3 for different data types
  • Automation scripts - Common setup and management tools

Node Directory Structure

Every node follows this layout:

node/
├── .host/                    # Host-level configs and links
│   ├── @tier1 -> /path/      # Symbolic links to storage
│   ├── @tier2 -> /path/
│   ├── @tier3 -> /path/
│   └── docker-compose.yml    # Host services (like backup)
├── service1/                 # Individual service stacks
│   ├── @tier1 -> ../.host/@tier1/service1/
│   ├── @tier2 -> ../.host/@tier2/service1/
│   ├── @tier3 -> ../.host/@tier3/service1/
│   ├── .env -> @tier1/.env
│   └── docker-compose.yml
└── service2/
    └── ...

Data Tier System

Every service uses the same data organization:

  • @tier1 - Configs, secrets, certificates (critical, small)
  • @tier2 - User data, databases (important, medium)
  • @tier3 - Cache, logs, temp files (disposable, large)

Services mount these as:

1
2
3
4

volumes:
  - ./@tier1/config:/config:ro
  - ./@tier2/data:/data
  - ./@tier3/cache:/cache

Standard Node Components

Traefik (Reverse Proxy)

Every node runs Traefik for.

  • Automatic HTTPS via Let’s Encrypt
  • Service discovery through Docker labels
  • Load balancing and routing

Socket Proxy

Secure Docker API access.

  • Read-only Docker socket
  • Limited API permissions
  • Isolated network access

Backup System

Automated data synchronization.

  • rclone for cloud backup
  • Telegram notifications
  • Tier-based backup frequency

Firewall Rules

Pre-defined ufw and ufw-docker rules.

  • automatic ufw-docker setup
  • firewalled containers
  • host rules

Service Communication

Same Node

Services communicate via Docker networks using service names or IP addresses.

Cross-Node

  • Tunnels for secure connections
  • Direct internet with firewall restrictions
  • Local network for home nodes

Common Patterns

Service Definition 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

services:
  app:
    image: app:latest
    networks:
      - enclave
      - root-proxy
    volumes:
      - ./@tier1/config:/config:ro
      - ./@tier2/data:/data
    labels:
      - "traefik.http.routers.app.rule=Host(`app.domain.com`)"

Health Monitoring 

1
2
3
4

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  retries: 3

Resource Limits 

1
2
3
4
5

deploy:
  resources:
    limits:
      memory: 512M
      pids: 100

This standardized approach means adding new services or setting up new nodes follows the same patterns every time.

Last updated on
Network Design