Senko-san
103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# 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
|
|
```
|