Project Phoenyx – Part 4: Order in Chaos (The Architecture)

Category: Core Stack / Architecture | Read Time: approx. 20 minutes

Introduction: The Monolith Problem

Anyone who has worked with Docker knows the problem: You start with a small docker-compose.yml. A web server, maybe a database. Then Traefik is added. Then monitoring. Then Crowdsec. And suddenly you have a file with 500 lines of code where no one can keep track anymore.

This leads to problems:

For Project Phoenyx, we use a modern feature of Docker Compose that only recently became stable and revolutionizes the way we build stacks: Includes.

The Concept: Instead of squeezing everything into one file, we create a main file (Master) that works like a table of contents and points to specialized sub-files.

1. The Master File: A Table of Contents

Our central docker-compose.yml is located in the root directory of our project (/opt/containers/docker-compose.yml). It does not define services directly. It delegates.

# The Headquarters: /opt/containers/docker-compose.yml
include:
  - ./networks/network.yml
  - ./socket-proxy/socket-proxy-docker-compose.yml
  - ./traefik/traefik-docker-compose.yml
  - ./crowdsec/crowdsec-docker-compose.yml
  - ./authentik/authentik-docker-compose.yml
  - ./mariadb/mariadb-docker-compose.yml

When we run the command docker compose up -d in the main directory now, Docker reads all these files, merges them in memory into a huge configuration, and executes them. To Docker, it is one stack. To us, they are cleanly separated modules.

The advantage is immense: If we want to work on the database, we only open mariadb-docker-compose.yml. We can't accidentally break anything in Traefik because that file isn't even open.


2. Deep Dive: The Network Architecture

Let's get to the heart of our infrastructure. Many tutorials make it easy: They create a single network (e.g., app-network) and throw all containers into it. This works, but from a security perspective, it's a nightmare. Why should the database be able to communicate directly with the web server if it is only needed by the app?

We are taking a more professional path. We use network segmentation and manual IPAM (IP Address Management).

[Image of network diagram with security zones]

Why Manual IPAM?

Normally, Docker randomly assigns IPs when starting containers (e.g., 172.18.0.x). This has disadvantages:

  1. Overlaps: If you have many stacks, networks can overlap.
  2. Firewall Rules: It is hard to write fixed rules ("Allow access from IP X") if IP X changes with every restart.
  3. Order: We want to know exactly which service lives where.

In our network.yml, we therefore define fixed subnets. We chose the block 172.28.0.0/14. This gives us enough space for everything we ever want to build.

Our Security Zones (Analyzing network.yml)

Let's look closely at the definitions in network.yml. We divide our infrastructure into logical blocks. Each block is a /25 subnet, giving us 128 IP addresses per network – more than enough for any purpose.

A. The High-Security Zones (Internal Networks)

These networks have the flag internal: true. This means: Containers in this network have no access to the internet and cannot be reached from the outside. It is a digital vault.

  # Example from network.yml
  database_internal:
    name: database_internal
    driver: bridge
    internal: true  # <--- The security switch!
    ipam:
      driver: default
      config:
      - subnet: 172.28.0.128/25

B. The Communication Zones (Attachable Networks)

These networks connect different stacks together. We use attachable: true here so that we can later attach containers from other compose files (e.g., a separate WordPress installation) to this network.

IPv6 - We Are Ready for the Future

A detail often overlooked: Our network.yml consistently enables IPv6 (enable_ipv6: true). We also assign an IPv6 subnet to each network (e.g., fd00:1:be:a:7001:0:1::/123). This makes our infrastructure future-proof, even though many Docker setups today still rely purely on IPv4.

Summary of Strategy:
We use the principle of "Least Privilege". A container is only a member of the networks it absolutely needs. A database needs no internet -> off to the internal net. A web server must be reachable -> off to the Traefik net.

What's Next?

We now have the foundation and the blueprint. The "roads" (networks) are built, the construction management (Docker Compose Master File) is ready. In the next part, we will start letting the first residents move in. We begin with the most important security feature: Protecting our Docker Socket.