Security Architecture

How security works across all nodes. Every node uses the same security patterns - container hardening, network isolation, secrets management, and access controls.

Container Security

Read-Only Filesystems

Services use read-only root filesystems when possible:

1
2
3
4
5
6
services:
  app:
    read_only: true
    tmpfs:
      - /tmp        # Writable temp space
      - /var/tmp

This prevents malware from modifying system files and keeps containers immutable.

Capability Management

Containers run with minimal required capabilities:

1
2
3
4
5
6
7
8
services:
  app:
    cap_drop:
      - ALL           # Drop everything
    cap_add:
      - SETUID        # Only add what's needed
      - SETGID
      - CHOWN

Common capability patterns:

File services: SETUID, SETGID, CHOWN
Network services: NET_ADMIN, SYS_MODULE
Most services: No extra capabilities needed

Security Context

All containers disable privilege escalation:

1
2
3
4
services:
  app:
    security_opt:
      - no-new-privileges:true

Resource Limits

Prevent resource exhaustion attacks:

1
2
3
4
5
6
7
services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M      # Memory limit
          pids: 100         # Process limit

Process Management

Use init system for proper signal handling:

1
2
3
services:
  app:
    init: true              # Docker's tini init

Network Security

Network Isolation

Four network types with different security properties:

Enclave Networks

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

Isolated from internet
Service-to-service communication only
Predictable IP ranges for firewall rules

Direct Networks

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

Controlled external connectivity
Explicit port mapping required
Firewall integration

Proxy Networks

1
2
3
4
networks:
  root-proxy:
    external: true
    internal: true          # No direct internet

Web access through reverse proxy
Automatic SSL termination
Request filtering and rate limiting

Socket Networks

1
2
3
networks:
  root-socket:
    internal: true          # Management only

Docker API access for management
No external connectivity
Audited operations

Docker Socket Security

Protected Docker API access:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1         # Allow container ops
      IMAGES: 0            # Block image ops
      VOLUMES: 0           # Block volume ops
      NETWORKS: 0          # Block network ops

This prevents containers from getting root access through the Docker API.

Secrets Management

Docker Secrets

Sensitive data uses Docker secrets:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
services:
  app:
    secrets:
      - api-token
    environment:
      API_TOKEN_FILE: /run/secrets/api-token

secrets:
  api-token:
    file: ./@tier1/secrets/api-token

Benefits:

Secrets mounted as read-only files
Not visible in environment variables
Automatic cleanup on container stop
Stored in @tier1 secure storage

Environment Variables

Use error-on-undefined for critical settings:

1
2
3
environment:
  DATABASE_PASSWORD: ${DB_PASSWORD:?error}
  API_KEY: ${API_KEY:?error}

Services fail to start if critical secrets are missing.

Configuration Isolation

Sensitive config isolated in @tier1:

1
2
3
4
volumes:
  - ./@tier1/config:/config:ro      # Read-only config
  - ./@tier1/secrets:/secrets:ro    # Read-only secrets  
  - ./@tier2/data:/data             # Read-write data

Access Control

User Management

Consistent user/group IDs:

1
2
3
4
5
6
services:
  app:
    environment:
      PUID: 1000            # User ID
      PGID: 1000            # Group ID
    user: "1000:1000"       # Explicit user

This ensures predictable file ownership and prevents privilege escalation.

Volume Security

Minimal read-write access:

1
2
3
4
5
6
7
volumes:
  # Read-only mounts
  - ./@tier1/config:/config:ro
  - ./@tier3/shared/media:/media:ro
  
  # Read-write only where needed
  - ./@tier2/database:/var/lib/database

Service Dependencies

Security services start first:

1
2
3
4
5
6
7
services:
  app:
    depends_on:
      auth:
        condition: service_healthy
      database:
        condition: service_started

SSL/TLS Security

Automatic HTTPS

All web services get automatic certificates:

1
2
3
4
5
6
7
services:
  traefik:
    command:
      - "--certificatesresolvers.cloudflare.acme.dnschallenge=true"
      - "--certificatesresolvers.cloudflare.acme.dnschallenge.provider=cloudflare"
    labels:
      - "traefik.http.routers.app.tls.certresolver=cloudflare"

Features:

Automatic renewal
DNS challenge (no port 80 needed)
Perfect Forward Secrecy
Strong cipher suites

TLS Configuration

Services can use TLS passthrough for VPN:

1
2
3
labels:
  - "traefik.tcp.routers.vpn.tls.passthrough=true"
  - "traefik.tcp.routers.vpn.rule=HostSNI(`vpn.domain.com`)"

Application Security

Database Security

Database integrity checks:

1
2
3
4
5
6
7
8
9
services:
  postgres:
    environment:
      POSTGRES_INITDB_ARGS: '--data-checksums'
    healthcheck:
      test: |
        pg_isready || exit 1;
        checksum_failures=$$(psql --tuples-only --no-align --command='SELECT COALESCE(SUM(checksum_failures), 0) FROM pg_stat_database');
        [ "$$checksum_failures" = '0' ] || exit 1

Health Monitoring

Comprehensive health checks:

1
2
3
4
5
6
7
8
services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Resource Protection

Prevent resource exhaustion:

1
2
3
4
5
6
7
deploy:
  resources:
    limits:
      memory: 1G
      pids: 200
    reservations:
      memory: 256M

Monitoring and Alerting

Security Events

Telegram notifications for security events:

1
2
# From automation scripts
setup_error_trap "Security Alert" "$TELEGRAM_BOT_URL" "$NODE"

Alerts for:

Service failures
Configuration errors
Certificate problems
Backup failures

Log Security

Logs isolated and secured:

1
2
3
volumes:
  - ./@tier3/logs:/var/log
  - /etc/localtime:/etc/localtime:ro

Security Principles

Defense in Depth

Multiple security layers:

Container isolation and hardening
Network segmentation
Application security
Data encryption

Least Privilege

Minimal container capabilities
Restricted network access
Read-only mounts where possible
Limited user permissions

Secure by Default

Services start with secure configs
Insecure options disabled
Required secrets must be provided
Automatic security updates

Zero Trust

No implicit trust between services
All communication authenticated
Network traffic filtered
Regular health validation

This security architecture protects your nodes while keeping operations simple and reliable.

Last updated on October 2, 2025

Data Tiers