⚠️ This project is under active development. Features may change, break, or be removed at any time. A management UI is planned.

A self-hosted homelab infrastructure built around Docker, Traefik, and Cloudflare — with a Leptos (Rust/WASM) web frontend in the works.

---

What is this?

This project is a personal homelab orchestration project. It manages multiple self-hosted services (Minecraft server, my portfolio, Minecraft server builder, Portainer, etc.) behind a Traefik reverse proxy, with automatic Cloudflare DNS management written bash. Basically, the goal is to have an automated service deployment based on containers, you build a container with the necessary labels in it and it automatically manages the DNS stuff.

---

How it works

Network layout

Two Docker networks are used:

• local — a private bridge network for isolated inter-container communication (Traefik routes traffic here).
• lab — a macvlan network with full IPv4/IPv6 support, giving containers real LAN addresses.

Traefik (reverse proxy)

Traefik listens on ports 80 and 443. All HTTP traffic is automatically redirected to HTTPS. Each service declares its own routing rules via Docker labels:

- "traefik.enable=true"
- "traefik.http.routers.mcserverbuilder.rule=Host(`minecraft.coisas-mais-estranhas.com.br`) || Host(`mcserverbuilder.com`)"
- "traefik.http.routers.mcserverbuilder.tls=true"

Traefik picks these up at runtime — no config file changes needed when adding a new service. TLS certificates are managed via Let's Encrypt on a Cerbot container and mounted from a shared volume.

Traefik also handles TCP/UDP passthrough (for now I made only hard coded minecraft server logic that will be soon integrated with minecraft server builder).

Cloudflare DNS automation

A Bash daemon (src/scripts/dns_records.sh) watches for Docker container start events and automatically creates or updates Cloudflare DNS records based on container labels:

- "cloudflare.domain=example.com"   # you can declare multiple domains positionally, separated by commas
- "cloudflare.subdomain=myapp"      # use "@" for root domain, if there are multiple domains declared, this is also positional and must be in the same order as the domains
- "cloudflare.type=CNAME"           # A, AAAA, CNAME, or SRV, also accept multiple entries separated by commas
- "cloudflare.cname_domain=target.com" # Only if type is CNAME, declares which domain to point to
- "cloudflare.srv.port=25565"       # Only if type is SRV, declares the port to point to
- "cloudflare.srv.proto=_tcp"       # Only if type is SRV, declares the protocol (TCP or UDP)
- "cloudflare.srv.service=_minecraft" # Only if type is SRV, declares the service (e.g. _minecraft, _http, etc.)
- "cloudflare.proxied=true"         # whether to enable Cloudflare proxy (CDN, DDoS protection, etc.)

The daemon reads these labels, resolves the container's public IPv4/IPv6 address, and calls the Cloudflare API to upsert the record. Multiple domains across different Cloudflare accounts and zone IDs are supported — each domain can have its own DOMAIN_XYZ_ZONE_ID and DOMAIN_XYZ_API_TOKEN env var, with a global default as fallback.

The flow end-to-end

Internet
   │
   ▼
Cloudflare (DNS + proxy)
   │
   ▼
Traefik (TLS termination + routing)
   │
   ├──▶ minecraft-server-builder
   ├──▶ vaultwarden
   ├──▶ portainer
   └──▶ FileBrowser
   └──▶ Other services...

---

Default Services

Service	Description
Portainer	Docker container management UI
Traefik	Reverse proxy and TLS termination

---

Default Templates

Template	Description
Minecraft Server Cluster	A template for setting up a cluster of Minecraft servers, with MC-Router for reverse proxying

---

Setup

Prerequisites

• Linux System (tested on Ubuntu Server 24.04)
• Docker with Compose
• A Cloudflare account with API token and zone ID
• A Brain and Patience

Configuration

Copy .env.example to .env and fill in your values:

CLOUDFLARE_API_TOKEN=your_token
CLOUDFLARE_ZONE_ID=your_zone_id

# macvlan network settings (match your LAN)
INTERFACE=enp2s0
IPV4_SUBNET=192.168.0.0/24
IPV4_GATEWAY=192.168.0.1
IPV4_RANGE=192.168.0.128/26
IPV6_SUBNET=fd00:abcd:1234::/64
IPV6_GATEWAY=fd00:abcd:1234::1

For multiple domains on different Cloudflare accounts, add per-domain overrides:

EXAMPLE_COM_ZONE_ID=...
EXAMPLE_COM_API_TOKEN=...

Bootstrap

# Create the Docker networks
bash src/scripts/docker_calls.sh create_lab_network
bash src/scripts/docker_calls.sh create_private_network

# Start a specific service
bash src/scripts/setup.sh start traefik

# Or start a new service interactively
bash src/scripts/setup.sh create_service

The DNS daemon starts automatically and watches for new containers:

bash src/scripts/dns_records.sh

---

Planned

• Management UI (Leptos web app) for controlling services, viewing DNS records, and monitoring containers.
• Dynamic TCP/UDP passthrough configuration in Traefik based on container labels (currently hardcoded for Minecraft).
• More service templates (PiHole, Vaultwarden, FileBrowser, Jellyfin, etc.).
• Better error handling and logging.
• Support for more DNS record types and advanced Cloudflare features (e.g. load balancing, workers, etc.).
• Automated installation and other stuff.

Contributing

Contributions are welcome, I will be more than grateful! Feel free to open issues or submit pull requests for bug fixes, new features, or improvements. Please, add tests, I will do my best to do so too. I will try to review and merge contributions as quickly as possible, but please be patient as this is a personal project and I may not have much time to dedicate to it. Thanks for your interest and support!

---

License

This is free, under the UNLINCESED license. See LICENSE.