initial

2026-06-08 12:49:45 +03:00
commit 1b251869c4
21 changed files with 1404 additions and 0 deletions
@@ -0,0 +1,102 @@
+# mcma-bootstrap
+
+Interactive installer for **MCMA** (My Cool Music App) — a self-hosted music
+service. One command asks a few questions, writes a `.env.deploy` and a
+`docker-compose.yml`, pulls the images, runs database migrations, creates the
+first admin, and verifies the stack is healthy.
+
+Zero dependencies beyond **bash 4+, Docker, and Docker Compose v2**. No jq, no
+Python, no yq. Secrets are generated for you and never printed.
+
+## Quick start
+
+```bash
+make deploy
+```
+
+That's it. The wizard walks you through:
+
+1. Language (English / Русский)
+2. Which services to run (backend is required; web UI optional)
+3. Image tag (`latest` or a pinned version)
+4. Database — built-in Postgres or an external one
+5. Redis — built-in or external
+6. Media storage — local directory, built-in MinIO (S3), or external S3
+7. Network — reverse proxy with automatic HTTPS, or a plain HTTP port
+8. The first administrator account
+9. An optional ML service URL
+
+Then it generates the config, pulls images, migrates, seeds the admin, starts
+everything, and waits for the API health check before declaring success.
+
+## Commands
+
+```bash
+make deploy     # run the installer (fresh install, or update/reconfigure menu)
+make update     # pull fresh images of the current tag, migrate, restart
+make up         # start the stack from the existing config
+make down       # stop the stack (data volumes are kept)
+make logs       # tail logs from all services
+make status     # container status + API health
+make clean      # stop and remove generated config (prompts before deleting data)
+```
+
+## What gets generated
+
+| File                  | Purpose                                  | Committed? |
+| --------------------- | ---------------------------------------- | ---------- |
+| `.env.deploy`         | All settings + generated secrets (0600)  | **No**     |
+| `docker-compose.yml`  | The stack, assembled from your choices   | **No**     |
+| `Caddyfile`           | Reverse-proxy routing (if proxy enabled) | **No**     |
+
+All three are in `.gitignore`. Re-running `make deploy` over an existing install
+offers to update images or reconfigure (backing up the old config first); it
+never silently overwrites.
+
+## Architecture notes
+
+- **One backend image, two roles.** `git.ollyhearn.ru/olly/mcma-backend` runs
+  the API (`uvicorn`, port 8000) and the background worker
+  (`arq app.workers.arq_worker.WorkerSettings`) — same image, different command.
+- **The web UI needs a reverse proxy.** `git.ollyhearn.ru/olly/mcma-webui` is a
+  prebuilt static SPA that calls `/api/v1` on its own origin and does not proxy
+  the API itself. So whenever the web UI is deployed, the installer puts **Caddy**
+  in front as the single entrypoint, routing `/api/*`, `/health*` and `/rest/*`
+  to the backend and everything else to the UI. Caddy runs plain HTTP on a port,
+  or gets automatic HTTPS if you provide a domain. A backend-only deploy skips
+  the proxy and publishes the API port directly.
+- **Startup is ordered and fails loud.** Backing services come up and become
+  healthy → migrations run → the first admin is created → app services start →
+  the API `/health` endpoint is polled. The backend is never started over a
+  database that failed to migrate.
+
+## Private registry
+
+The images live in a private registry. If `make deploy` reports `unauthorized`
+while pulling, log in first:
+
+```bash
+docker login git.ollyhearn.ru
+```
+
+## Creating an admin later
+
+If you skipped admin creation during setup:
+
+```bash
+docker compose --project-name mcma --env-file .env.deploy -f docker-compose.yml \
+  run --rm --no-deps api mcma create-admin <username>
+```
+
+## Layout
+
+```
+mcma-bootstrap/
+├── Makefile              # thin entrypoint → deploy.sh
+├── deploy.sh             # wizard + lifecycle orchestrator
+├── lib/                  # bash modules (ui, i18n, checks, secrets, generators, lifecycle)
+├── templates/
+│   ├── compose/          # per-service compose fragments, glued by choice
+│   └── env/env.template  # base .env with @TOKEN@ placeholders
+└── i18n/                 # ru / en string tables
+```