From 5561d54a248259b78ca681e7d7dee192b99a070f Mon Sep 17 00:00:00 2001
From: lila <beiweitemderbeste@protonmail.com>
Date: Thu, 26 Mar 2026 09:43:39 +0100
Subject: [PATCH] feat(infra): add docker-compose and dockerfiles for all
 services

---
 .gitignore                 |  3 +++
 documentation/CLAUDE.md    |  1 +
 documentation/decisions.md | 50 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+)

diff --git a/.gitignore b/.gitignore
index 9c15430..03b6ab8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,6 @@ dist/
 build/
 .env
 **/*.tsbuildinfo
+.repomixignore
+repomix.config.json
+repomix/
diff --git a/documentation/CLAUDE.md b/documentation/CLAUDE.md
index b3399d3..0c067f0 100644
--- a/documentation/CLAUDE.md
+++ b/documentation/CLAUDE.md
@@ -13,6 +13,7 @@
 ## Rules
 
 - **No code from the mentor** — explanations, directions, and feedback only
+- **documentation and reasoning** - is expilicitly allowed and to be created/written
 - **No implementing before discussing** — always align on the approach first
 - **Commit after every approved checkbox**
 - The mentor suggests commit messages when asked
diff --git a/documentation/decisions.md b/documentation/decisions.md
index a8da3b4..41e6196 100644
--- a/documentation/decisions.md
+++ b/documentation/decisions.md
@@ -28,6 +28,28 @@ All auth delegated to OpenAuth service at `auth.yourdomain.com`. Providers: Goog
 
 ---
 
+## Docker
+
+### Multi-stage builds for monorepo context
+
+Both `apps/web` and `apps/api` use multi-stage Dockerfiles (`deps`, `dev`, `builder`, `runner`) because:
+
+- The monorepo structure requires copying `pnpm-workspace.yaml`, root `package.json`, and cross-dependencies (`packages/shared`, `packages/db`) before installing
+- `node_modules` paths differ between host and container due to workspace hoisting
+- Stages allow caching `pnpm install` separately from source code changes
+
+### Vite as dev server (not Nginx)
+
+In development, `apps/web` uses `vite dev` directly, not Nginx. Reasons:
+
+- Hot Module Replacement (HMR) requires Vite's WebSocket dev server
+- Source maps and error overlay need direct Vite integration
+- Nginx would add unnecessary proxy complexity for local dev
+
+Production will use Nginx to serve static Vite build output.
+
+---
+
 ## Architecture
 
 ### Express app structure: factory function pattern
@@ -84,6 +106,34 @@ Using Vitest globals (`describe`, `it`, `expect` without imports) requires `"typ
 
 ---
 
+## Known Issues / Dev Notes
+
+### glossa-web has no healthcheck
+
+The `web` service in `docker-compose.yml` has no `healthcheck` defined. Reason: Vite's dev server (`vite dev`) has no built-in health endpoint. Unlike the API's `/api/health`, there's no URL to poll.
+
+Workaround: `depends_on` uses `api` healthcheck as proxy. For production (Nginx), add a health endpoint or use TCP port check.
+
+### Valkey memory overcommit warning
+
+Valkey logs this on start in development:
+
+```text
+WARNING Memory overcommit must be enabled for proper functionality
+```
+
+This is **harmless in dev** but should be fixed before production. The warning appears because Docker containers don't inherit host sysctl settings by default.
+
+Fix: Add to host `/etc/sysctl.conf`:
+
+```conf
+vm.overcommit_memory = 1
+```
+
+Then `sudo sysctl -p` or restart Docker.
+
+---
+
 ## Current State
 
 ### Completed checkboxes (Phase 0)