From 1ce42bb16de70c5548046acbc81ef9f3c7a21cf8 Mon Sep 17 00:00:00 2001
From: Marco <marco.kunitz@googlemail.com>
Date: Tue, 30 Jun 2026 11:13:06 +0000
Subject: [PATCH] add readme with stack overview

---
 README.md | 66 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 44 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index e215bc4..b7d351e 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,58 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# my-app
 
-## Getting Started
+A Next.js application deployed on a self-hosted infrastructure stack.
 
-First, run the development server:
+## Stack Overview
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+```
+Browser
+  └── Caddy (reverse proxy, TLS termination)
+        ├── my-app.mk360.de    → Next.js (Docker, port 3003)
+        ├── git.mk360.de       → Gitea (port 3000)
+        ├── coolify.mk360.de   → Coolify (port 8000)
+        ├── monitor.mk360.de   → Uptime Kuma (10.0.1.7)
+        └── paperclip.mk360.de → Paperclip (port 3100)
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### Why Next.js?
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Next.js provides server-side rendering, file-based routing, and built-in TypeScript support out of the box. It compiles to a [standalone output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files) (`output: "standalone"`) which produces a minimal Docker image (~100 MB) containing only the files needed to run the app — no `node_modules` bloat in the final image.
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+### Why Coolify?
 
-## Learn More
+Coolify is a self-hosted deployment platform (similar to Vercel/Heroku) that manages Docker containers, handles rolling updates, and provides a deployment UI and API. It replaces the need for a managed cloud provider, keeping everything on the mk360.de server.
 
-To learn more about Next.js, take a look at the following resources:
+The CI/CD pipeline works as follows:
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+```
+git push
+  └── Gitea webhook → Caddy /deploy/my-app → Coolify API
+        └── Coolify clones repo, builds Docker image, rolling update
+```
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+> Note: Coolify's native Gitea webhook endpoint requires OAuth source integration.
+> The `/deploy/my-app` Caddy route acts as a bridge, injecting the Coolify API
+> bearer token so Gitea's plain webhook can trigger authenticated deploys.
 
-## Deploy on Vercel
+## Subdomains
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+| Subdomain | Service | Backend |
+|-----------|---------|---------|
+| `my-app.mk360.de` | This Next.js app | `127.0.0.1:3003` |
+| `git.mk360.de` | Gitea — self-hosted Git | `127.0.0.1:3000` |
+| `coolify.mk360.de` | Coolify — deployment platform | `127.0.0.1:8000` |
+| `monitor.mk360.de` | Uptime Kuma — uptime monitoring | `10.0.1.7:80` |
+| `paperclip.mk360.de` | Paperclip | `127.0.0.1:3100` |
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+All subdomains are served over HTTPS via Caddy with automatic TLS certificates.
+
+## Build & Deploy
+
+The app is built using a multi-stage Dockerfile with BuildKit cache mounts:
+
+- **`deps` stage** — installs npm packages, cached via `--mount=type=cache,target=/root/.npm`
+- **`builder` stage** — runs `next build`, cached via `--mount=type=cache,target=/app/.next/cache`
+- **`runner` stage** — minimal Alpine image, copies only the standalone output
+
+This keeps subsequent deploys fast even though Coolify builds with `--no-cache` by default,
+since BuildKit cache mounts persist independently of the layer cache.