From 19d41f3041a426cbbfcfbe66ae367b297ae9e5c5 Mon Sep 17 00:00:00 2001
From: Robert Rapp <robert.rapp@mindboost.team>
Date: Mon, 15 Sep 2025 19:38:57 +0200
Subject: [PATCH] docs(infra): document new infra v2 structure and usage

---
 README.md     | 26 +++++++++++++++++++++++++-
 docs/infra.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 docs/infra.md

diff --git a/README.md b/README.md
index a76bb7c..4531199 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,30 @@
 
 All the software used and hosted by mindboost organized in containers.
 
+## New Infra (v2) Overview
+
+This repo now includes a modular, best‑practice infrastructure under `infra/` to make replication and selective deployment easy. It is centered on Traefik as the reverse proxy with automatic TLS via Let's Encrypt, environment layering, and pick‑what‑you‑need application stacks.
+
+- Core: `infra/core/traefik` — Traefik with HTTPS (ACME), dashboard, and sane defaults
+- Apps: `infra/apps/<service>` — self‑contained stacks (e.g., `nextcloud`)
+- Env: `infra/env/<environment>/common.env` — environment defaults (dev/prod)
+- Secrets: `infra/secrets/` — local secret storage (ignored by git)
+- Make targets: top‑level `Makefile` to bootstrap, start proxy, and start apps
+
+Quickstart
+
+- Copy `infra/env/development/common.env` and adjust domains and ACME email.
+- Create the shared proxy network and ACME storage: `make bootstrap`
+- Start Traefik: `make proxy-up`
+- Start a service, e.g. Nextcloud: `make app-up APP=nextcloud`
+
+Notes
+
+- Traefik dashboard is exposed at `TRAEFIK_DASHBOARD_DOMAIN` with optional basic auth.
+- Services connect to an external `proxy` network for routing, plus their own internal network.
+- Each app has its own `.env.example`; copy to `.env` and adjust.
+- The legacy `apps/` structure remains as-is; new infra is additive and can coexist.
+
 ## Project Structure
 
 ./apps/
@@ -187,4 +211,4 @@ These scripts can be run from the command line to perform various tasks related
 To use a script, navigate to the scripts directory and run:
 
 ```bash
-./script-name.sh
\ No newline at end of file
+./script-name.sh
diff --git a/docs/infra.md b/docs/infra.md
new file mode 100644
index 0000000..80ac671
--- /dev/null
+++ b/docs/infra.md
@@ -0,0 +1,29 @@
+Infrastructure v2
+
+Goals
+
+- Modular stacks you can pick individually (Nextcloud, etc.)
+- Unified reverse proxy (Traefik) with automatic TLS
+- Clear env layering and git‑ignored secrets
+- Simple Make targets for a smooth DX
+
+Layout
+
+- infra/core/traefik: Traefik compose + static/dynamic config
+- infra/apps/<service>: Self‑contained compose stacks and .env.example
+- infra/env/<env>/common.env: Shared environment defaults per environment
+- infra/secrets: Local secret files (ignored)
+- scripts/infra/bootstrap.sh: Creates proxy network and ACME storage
+
+Usage
+
+1. cp infra/env/development/common.env infra/env/development/common.env (adjust values)
+2. make bootstrap
+3. make proxy-up
+4. make app-up APP=nextcloud
+
+Security
+
+- Do not commit real secrets. Place them in local `.env` files or secret managers.
+- Optionally protect Traefik dashboard with basic auth via `TRAEFIK_BASIC_AUTH_USERS`.
+