Add a Makefile so a fresh clone can be running in one call #153

Merged

qwc merged 2 commits from feature/makefile-quickstart into main

2026-09-01 20:50:37 +02:00

qwc commented

2026-09-01 20:33:28 +02:00

Owner

docker-compose.yml mounts ./config.yaml read-only, and that file doesn't exist in a fresh clone;
the shipped example's admin password is admin, which the server refuses to create an account with, so a first run fails with a password-strength message instead of starting;
every setting has an ASIAKIRJAT_ env override and a missing config file falls back to defaults — so a playground needs no config file at all.

The headline

make demo

Builds the image, runs it, waits for /healthz, and prints:

  Asiakirjat is running.

    URL:       http://localhost:8080
    Username:  admin
    Password:  Cy2q...

    make logs    follow the log
    make stop    stop it, keeping its data
    make reset   stop it and delete its data

make help lists everything; any variable overrides (make demo PORT=9000).

Decisions worth reviewing

The generated password is kept in .demo-password (gitignored, 0600). The admin account is created only on a container's first start, so regenerating it each run would print credentials that stopped working after the first make demo.
Data lives in a named volume, so stop → demo keeps it and reset deliberately doesn't.
The image is tagged asiakirjat:local, not by version — it's rebuilt constantly and versioned tags would leave a pile behind. VERSION is still stamped into the binary via ldflags.
make config + make compose-up keep the config-file path for when you do want to edit one.

What I verified, and what I didn't

Verified: build, help, config, clean, and — the one the demo actually rests on — that the binary starts with no config file present, from env alone, and puts its database and projects under ./data, which is what the container mounts as its volume.

That check also caught a bug in this Makefile: run used ASIAKIRJAT_PORT, but the real variable is ASIAKIRJAT_SERVER_PORT, so PORT= was being silently ignored. Fixed.

Not verified: the Docker targets themselves — there is no Docker in this environment. make -n demo expands correctly, but docker build / docker run have not actually been executed. Worth one manual make demo before merging.

Assisted-by: Claude Opus 5

There was no fast path from clone to something you can log into. The pieces existed — Dockerfile, compose file, config example — but stitching them together meant knowing three things written down nowhere: - `docker-compose.yml` mounts `./config.yaml` read-only, and that file doesn't exist in a fresh clone; - the shipped example's admin password is `admin`, which the server **refuses** to create an account with, so a first run fails with a password-strength message instead of starting; - every setting has an `ASIAKIRJAT_` env override and a missing config file falls back to defaults — so a playground needs no config file at all. ## The headline ```bash make demo ``` Builds the image, runs it, waits for `/healthz`, and prints: ``` Asiakirjat is running. URL: http://localhost:8080 Username: admin Password: Cy2q... make logs follow the log make stop stop it, keeping its data make reset stop it and delete its data ``` `make help` lists everything; any variable overrides (`make demo PORT=9000`). ## Decisions worth reviewing - **The generated password is kept in `.demo-password`** (gitignored, 0600). The admin account is created only on a container's *first* start, so regenerating it each run would print credentials that stopped working after the first `make demo`. - **Data lives in a named volume**, so `stop` → `demo` keeps it and `reset` deliberately doesn't. - **The image is tagged `asiakirjat:local`**, not by version — it's rebuilt constantly and versioned tags would leave a pile behind. `VERSION` is still stamped into the binary via ldflags. - `make config` + `make compose-up` keep the config-file path for when you *do* want to edit one. ## What I verified, and what I didn't Verified: `build`, `help`, `config`, `clean`, and — the one the demo actually rests on — that the binary starts with **no config file present**, from env alone, and puts its database and projects under `./data`, which is what the container mounts as its volume. That check also caught a bug in this Makefile: `run` used `ASIAKIRJAT_PORT`, but the real variable is `ASIAKIRJAT_SERVER_PORT`, so `PORT=` was being silently ignored. Fixed. **Not verified: the Docker targets themselves — there is no Docker in this environment.** `make -n demo` expands correctly, but `docker build` / `docker run` have not actually been executed. Worth one manual `make demo` before merging. Assisted-by: Claude Opus 5

qwc added 1 commit

2026-09-01 20:33:28 +02:00

Add a Makefile so a fresh clone can be running in one call

CI / test (pull_request) Successful in 1m29s

Details

CI / build (pull_request) Successful in 49s

Details

CI / docker (pull_request) Has been skipped

Details

3e707e6d6a

There was no fast path from clone to something you can log into. The pieces
existed — a Dockerfile, a compose file, a config example — but stitching them
together meant knowing three things that are not written down anywhere:

  - docker-compose.yml mounts ./config.yaml read-only, and that file does not
    exist in a fresh clone;
  - the shipped example's admin password is "admin", which the server refuses
    to create an account with, so a first run fails with a message about
    password strength rather than starting;
  - every setting has an ASIAKIRJAT_ environment override, and a missing
    config file falls back to defaults, so a playground needs no config file
    at all.

`make demo` builds the image, runs it, waits for /healthz, and prints the URL
and the credentials it generated. make logs / stop / reset cover the rest.

The generated admin password is written to .demo-password and kept, because
the admin account is only created on a container's first start: a fresh
password each run would print credentials that stopped working after the first
one. The demo's data lives in a named volume, so stop and demo round-trips
keep it and reset deliberately does not.

The image is tagged asiakirjat:local rather than by version — it is rebuilt
constantly and versioned tags would leave a pile behind. VERSION is still
stamped into the binary.

make config and make compose-up keep the config-file path for when you do want
to edit one.

Verified: build, help, config and the env-only startup the demo relies on —
the binary comes up with no config file present and puts its database and
projects under ./data, which is what the container mounts. The docker targets
themselves are unverified: there is no Docker in this environment.

Assisted-by: Claude Opus 5

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Marcel M. Otte <marcel.otte@mmo.to>

qwc added 1 commit

2026-09-01 20:45:46 +02:00

Say when the demo's URL is not reachable from your browser

CI / test (pull_request) Successful in 1m26s

Details

CI / build (pull_request) Successful in 49s

Details

CI / docker (pull_request) Has been skipped

Details

b9dd91263c

The port is published on the loopback of whichever machine runs Docker. Over
SSH that is the machine you are logged into, not the one your browser runs on,
and the symptom is indistinguishable from the server being down: make demo
reports it healthy, and the browser says connection refused.

When SSH_CONNECTION is set, print the ssh -L line that forwards it.

uname -n rather than hostname: hostname is not in every base image or minimal
shell environment, and a missing one would print "user@" — a broken command to
copy and paste, which is worse than no hint at all.

Assisted-by: Claude Opus 5

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Marcel M. Otte <marcel.otte@mmo.to>

qwc merged commit 4c48254393 into main

2026-09-01 20:50:37 +02:00

qwc deleted branch feature/makefile-quickstart

2026-09-01 20:50:37 +02:00

qwc referenced this pull request from a commit

2026-09-01 20:50:38 +02:00

Merge pull request 'Add a Makefile so a fresh clone can be running in one call' (#153) from feature/makefile-quickstart into main