Skip to content

An install script, a server stack, and a version to install - #9

Merged
Slicit merged 3 commits into
mainfrom
feat-install-on-a-server
Sep 11, 2026
Merged

Slicit merged 3 commits into
mainfrom
feat-install-on-a-server

Conversation

@Slicit

@Slicit Slicit commented Sep 11, 2026

Copy link
Copy Markdown
Owner

Componium could be run from a checkout and demonstrated with one compose command, and there was no way to put it on a server and keep it there. This is that, shaped like the sibling project's.

curl -fsSL https://raw.githubusercontent.com/Slicit/componium/main/install.sh | bash
/opt/componium/update.sh

What is here

deploy/docker-compose.server.yml is not the demonstration beside it. That one generates a clip, seeds a score and loops a player so somebody with no films and no hardware can see the system work. This one assumes films exist: the studio and its database, and nothing else unless asked. The player, conductor and software instrument are a show profile, off by default, because a server in a cupboard has no reason to be driving a fan.

Films, scores and rigs stay plain directories on the host, not named volumes. A film is large, it is the operator's, and the first thing anybody does is copy one in or back one up; a named volume puts it where only Docker can reach. The one named volume is the database, and everything in it rebuilds from the files above — which is what makes losing it an afternoon rather than a loss.

release.yml gives the installer something to install. CI publishes :main and a tag per commit, which is right for a box that follows the branch and wrong for latest: that has to mean a version somebody cut on purpose. Tagging v0.2.0 publishes :0.2.0, moves :latest, and opens a release for install.sh to resolve.

The bug that justified the whole exercise

A fresh install has no films and no scores, and the studio refused to start:

componium: no score given and none found in /scores

…a directory whose entire purpose is to be filled by the page that would not open. The container restarted forever.

An empty library now opens on an empty score: written to disk, because every path downstream expects a score with somewhere to be saved; carrying one empty track, because the format will not write a score without one; addressed at the first instrument the rig names, so the track that exists is one this installation can actually play. Naming a score that is missing still fails, which is the case refusing was right for. Three tests.

Verified by installing it

A throwaway directory, an image built from this tree, a real compose up under its own project name so the box's own stack was untouched, and the studio loaded in a real browser with no console errors on a zero-duration score. The library says "No films here yet. Upload one to get started."

Two smaller things the same run turned up: confirm answering "no" as the last statement of a function ends the installer under set -e, and an .env inside deploy/ would be deleted by the first update, which replaces that directory wholesale.

🤖 Generated with Claude Code

Slicit and others added 3 commits September 11, 2026 12:00
Componium could be run from a checkout and demonstrated with one compose
command, and there was no way to put it on a server and keep it there. This is
that, shaped like the sibling project's: install.sh asks four questions, writes
them down, pulls one image and starts; update.sh is the same script with the
answers already given.

deploy/docker-compose.server.yml is not the demonstration beside it. That one
generates a clip, seeds a score and loops a player so somebody with no films
and no hardware can see the system work. This one assumes films exist and that
the scores it writes are worth keeping: the studio and its database, and
nothing else unless asked. The player, the conductor and a software instrument
are a `show` profile, off by default, because a server in a cupboard has no
reason to be driving a fan.

Films, scores and rigs stay plain directories on the host rather than named
volumes. A film is large, it is the operator's, and the first thing anybody
does is copy one in or back one up; a named volume puts it where only Docker
can reach. The one named volume is the database, and everything in it can be
rebuilt from the files above, which is what makes losing it an afternoon
rather than a loss.

release.yml gives the installer something to install. CI publishes :main and a
tag per commit, which is right for a box that follows the branch and wrong for
"latest": that has to mean a version somebody cut on purpose. Tagging v0.2.0
publishes :0.2.0, moves :latest and opens a release, and install.sh resolves
the newest one.

Running it found a bug worth the whole exercise. A fresh install has no films
and no scores, and the studio refused to start: "no score given and none found
in /scores", a directory whose entire purpose is to be filled by the page that
would not open. The container restarted forever. So an empty library now opens
on an empty score, written to disk because every path downstream expects a
score with somewhere to be saved, carrying one empty track because the format
will not write a score without one, addressed at the first instrument the rig
names so that the track that exists is one this installation can play. Naming
a score that is missing still fails, which is the case refusing was right for.

Verified by installing it: a throwaway directory, an image built from this
tree, a real `compose up` under its own project name so the box's own stack
was untouched, and the studio loaded in a browser with no console errors on a
zero-duration score. The library says "No films here yet. Upload one to get
started", which is what a first run should say.

Two smaller things the same run turned up: `confirm` answering "no" as the
last statement of a function ends the installer under `set -e`, and an .env
inside deploy/ would be deleted by the first update, which replaces that
directory wholesale.

Co-Authored-By: Claude Opus 5 <[email protected]>
The studio had no authentication of any kind. That was defensible while it was
something you ran on your laptop against your own films, and stopped being
defensible the moment it was something you install on a server: it can delete
films, rewrite rigs, hold the shared secret for every board in the house, and
drive real hardware in a room with people in it.

Nothing is reachable now without a session. The exception is /firmware/, which
an ESP32 fetches when told to update itself: a board has no cookie jar and no
way to be given a password, so putting it behind the session would mean no
board could ever update again. It serves image files; the dangerous half of
that feature, telling a board to go and fetch one, is an admin route.

Three roles. A viewer watches and changes nothing, an operator authors scores
and runs shows, an admin also owns the hardware, the credentials for it, and
who else may sign in.

## Default deny, from one table

Every route is listed in auth.go with the weakest role that may read it and
the weakest that may change through it, and a request whose route is not in
that table is refused. A test walks the registrations in studio.go and fails
if one is missing, and fails the other way too if a rule names a route that no
longer exists. That is the only arrangement that survives somebody adding a
handler in six months: an allow-list you can forget to update is one that is
wrong, and here forgetting locks a new route down rather than opening it.

The split is read against write rather than method by method, because that is
how these handlers are built: one function serving GET to look and POST to
change.

## No new dependency

PBKDF2-HMAC-SHA256 from the standard library, 600,000 iterations, a salt each.
A project that pulls in a crypto library for one function owns that library's
release schedule forever, and crypto/pbkdf2 has been in the standard library
since Go 1.24.

It is a real trade and the comment says so: argon2id resists a GPU better
because it is memory-hard and this is not. What makes it defensible is the
shape of the threat here, and the encoded hash carries its own parameters, so
changing the scheme later does not lock anybody out.

## The first administrator

Made on the first start, with a generated password written to
state/initial-admin-password.txt at 0600 and nowhere else. Not the log, not
the environment: logs get shipped somewhere and environments get printed by
every debug page ever written. The installer reads that file and prints it
once, and says where it is.

The generated password avoids l, 1, I, O and 0, because it gets retyped by
hand exactly once and a character pair nobody can tell apart turns that into
three attempts and a suspicion the system is broken.

## Three things found by running it

A studio given only -score wrote its user list and that password into whatever
directory it was launched from, because filepath.Join("", "users.toml") is a
relative path. The test suite did it and left both files in the source tree.

The vite dev server proxies only what the studio owns, so /signin came back as
the application's own index.html and the form never appeared. That is also why
the redirect for a signed-out browser is tested in Go rather than in the
browser suite: in front of the dev server it never happens, and asserting it
there would be asserting a property of the dev server.

Where you land after signing in is always the front page, and cannot be
anything else: which section you were looking at lives in the hash, and a hash
is never sent to a server. Written down in the spec because it looks like
something that was forgotten.

Co-Authored-By: Claude Opus 5 <[email protected]>
Six things in it were not true, and the worst one had been wrong for months
without anything noticing.

The score it shows wrote a cue as

    { t = "...", action = "gust", intensity = 0.8, duration = "4s" }

with the intensity beside the action rather than inside params. That is not a
parse error. TOML ignores a key the struct does not have, so the file
validates, prints a clean summary, and loads with an empty parameter map: a
fan told to gust at nothing. The only symptom is silence, in a feature whose
entire job is to make something happen. The same block wrote colours as 0 to
255 while every real score in the repository writes 0 to 1.

Both are corrected, and the README's own block is now extracted and loaded by
a test rather than copied into a fixture, because a fixture is a second thing
that can agree with the code while the documentation quietly stops doing so.
It checks that every cue arrives carrying parameters, which is what the broken
version failed while loading perfectly, and both original faults were put back
to watch it fail.

The rest:

ROADMAP.md was linked from the documentation list and does not exist. The
milestones are LOGBOOK.md's table, so it points there.

"None of it has ever driven a physical device" stopped being true with the
fan. It now says what has actually run: one fan, on an ESP32, through a
MOSFET, with thresholds measured rather than guessed, and nothing else.

The vocabulary defined "pit" as the hub instruments register with. There is no
pit anywhere in this codebase and there never has been. Replaced with rig,
which is a word the software uses.

Nothing said the studio is private now. Somebody following the install command
would meet a sign-in form with no warning and no idea where the password is.
Both the server section and the local one say so.

The command table was missing import-vision.

Co-Authored-By: Claude Opus 5 <[email protected]>
@Slicit
Slicit merged commit bb02355 into main Sep 11, 2026
9 checks passed
@Slicit
Slicit deleted the feat-install-on-a-server branch September 11, 2026 16:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant