Exodus Server — Infrastructure & Service Architecture

This repository contains the complete infrastructure configuration and deployment setup for Exodus Server, a self-hosted homelab environment managed via Docker Compose.

The stack powers personal web services, media streaming, private search, network-level ad blocking, game server hosting, automated monitoring, and AI firewall protection.

---

Architecture & Network Security

The system consists of 22 Docker services organized into logical operational layers and strict network namespaces to enforce isolation and zero-trust principles. The main docker-compose.yml intelligently includes modular configuration files from the compose/ directory.

Network Isolation Spaces

• frontend_net: External-facing proxies, tunnels, and web frontends.
• backend_net: Internal caching, monitoring, and telemetry.
• media_net: Isolated network for torrent clients and music streaming.
• gaming_net: Dedicated network for Minecraft, its tunnels, and web maps.
• db_net: Completely isolated network for internal databases (Zipline PostgreSQL).
• socket_net: Internal network specifically for the Docker Socket Proxy.

1. Security & Protection Layer (compose/core.yml & compose/web.yml)

• Docker Socket Proxy (socket-proxy): Critical security boundary that prevents containers from directly mounting /var/run/docker.sock. It exposes a read-only API to internal services on the socket_net.
• Anubis (anubis, anubis-website, anubis-map): AI-resistant proof-of-work security proxies positioned in front of public services to mitigate bot traffic and scraping. Enforced with read-only file systems.
• Pi-hole (pihole): Network-wide DNS sinkhole providing ad blocking and local DNS resolution. Uses custom upstream resolvers (1.1.1.1, 1.0.0.1) and custom host lists.
• Fail2ban (fail2ban-jail.local): System-level jail configuration protecting SSH access.

2. Networking & Tunneling Layer (compose/core.yml & compose/gaming.yml)

• Cloudflare Tunnel (cloudflared): Establishes secure outbound tunnels to route HTTP/HTTPS traffic to internal services without opening public inbound router ports.
• Playit Tunnel (playit): Outbound tunnel provider specifically configured for routing low-latency TCP/UDP traffic to the Minecraft server.

3. Web Services & Frontends Layer (compose/web.yml)

• Personal Website (website): Modernized Vite + React / TypeScript single-page application served via high-performance Nginx (nginx:alpine) on a read-only file system.
• Homarr (homarr): Unified server dashboard replacing legacy homepage configurations. Uses localized configuration schemas and SQLite storage.
• IT-Tools (it-tools): Collection of developer and system administrator web utilities.
• PixivFE (pixivfe): Lightweight, privacy-respecting alternative frontend proxy for Pixiv.

4. Media & File Management Layer (compose/media.yml)

• qBittorrent (qbittorrent): Headless torrent client enhanced with the VueTorrent modern web user interface.
• Slskd (slskd): Soulseek network client configured for remote API configuration and media music directory synchronization.
• Navidrome (navidrome): Lightweight music streaming server reading directly from local music media volume.
• Zipline (zipline, zipline_db): Self-hosted media storage and file upload service backed by a dedicated PostgreSQL database container.

5. Gaming & Specialized Hosting Layer (compose/gaming.yml)

• Minecraft Server (minecraft): Purpur high-performance Minecraft server running on Java with RCON integration and auto-pause capabilities.
• Minecraft Backups (backups): Dedicated backup container executing scheduled 12-hour backups of world state into ./backups.
• BlueMap Server (bluemap-server): Standalone Nginx web server rendering pre-compressed 3D Minecraft world maps. Enforced with a read-only file system.

6. Search & Caching Layer (compose/web.yml)

• SearXNG (searxng): Metasearch engine running with custom CSS overrides, injected custom scripts, and DuckDuckGo fallback integrations.
• Valkey (valkey): Redis-compatible in-memory caching backend for SearXNG query optimization.

7. Monitoring & Management Layer (compose/core.yml)

• Uptime Kuma (uptime-kuma): Real-time HTTP, TCP, and DNS availability monitoring engine.
• AutoKuma (autokuma): Automatic monitor discovery service using Docker labels (kuma.*). Connects securely via the Socket Proxy.
• Dashdot (dashdot): Hardware status and container resource utilization display.
• Dozzle (dozzle): Real-time log viewer for inspectable container logs across the Docker daemon.
• Watchtower (watchtower): Automated container updater running nightly at 04:00 to prune old images.
• Portainer (portainer): Web UI container management platform.

---

Directory Structure

.
├── .env                       # Active environment credentials (git-ignored)
├── .env.example               # Sanitized environment template
├── .gitignore                 # Repository exclusions
├── README.md                  # Infrastructure documentation
├── docker-compose.yml         # Master compose file containing network declarations and includes
├── zipline.env                # Active Zipline credentials (git-ignored)
├── zipline.env.example        # Sanitized Zipline environment template
│
├── anubis/                    # Anubis AI Firewall policy definitions
├── bluemap-nginx.conf         # Nginx configuration for BlueMap standalone server
├── compose/                   # Modular Docker Compose files
│   ├── core.yml               # Infrastructure, security, and monitoring
│   ├── gaming.yml             # Game servers and related tunnels
│   ├── media.yml              # Media management and storage
│   └── web.yml                # Web frontends and dashboards
├── etc-dnsmasq.d/             # Custom Dnsmasq configurations for Pi-hole
├── etc-pihole/                # Pi-hole configuration (static lists tracked)
├── fail2ban-jail.local        # System fail2ban jail configuration
├── homarr/                    # Homarr dashboard configuration
├── pixivfe-proxy/             # PixivFE reverse proxy Nginx configuration
├── qbittorrent/               # qBittorrent & VueTorrent configuration
├── scripts/                   # System automation scripts
│   └── disk-alert.sh          # Cron-based disk space monitoring script
├── searxng/                   # SearXNG settings, CSS overrides, and injection script
├── slskd/                     # Slskd configuration template
└── website/                   # Personal website source code & Nginx server

---

Environment & Secrets Management

Secrets and sensitive tokens are strictly decoupled from version control using standard .env patterns.

1. Primary Credentials (.env):

   • Stores passwords for Pi-hole, Minecraft RCON, Playit tunnel secrets, Cloudflare tokens, Homarr encryption keys, PostgreSQL credentials, Uptime Kuma authentication, Watchtower Discord webhooks, and Slskd logins.
   • Referenced directly in docker-compose.yml via standard variable interpolation (${VAR_NAME}).

2. Service Environment Files (zipline.env):

   • Holds dedicated database credentials for PostgreSQL and Zipline session secrets.

3. Templates (.env.example, zipline.env.example):

   • Sanitized reference templates maintained in Git to allow quick environment provisioning on fresh nodes without exposing secrets.

---

Deployment & Operation

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2+

Starting the Stack

To initialize or update the entire stack:

docker compose up -d --remove-orphans

Checking Configuration Validity

To validate compose syntax and environment variable substitution without deploying:

docker compose config --quiet

Managing Individual Services

To restart or view logs for a specific service:

docker compose restart <service-name>
docker compose logs -f <service-name>