Running chords#

chords is one server: a Python backend that keeps everything in a single SQLite database and serves the web app itself. You can run it in Docker behind Caddy, which gets a TLS certificate for your domain, or run the backend directly.

What you need#

  • Docker with Compose, for the container setup.
  • Python 3.11 or newer, to run butler.py, the task runner that drives every command below. The first run downloads its harness, so it needs network access. Nothing else has to be installed by hand.
  • Node.js, to compile the web app before an image is built.
  • A domain pointing at the machine, with ports 80 and 443 open, if you want HTTPS.
  • An OpenRouter key, only if you want to import songs. Everything else works without one.

Get the source:

git clone https://github.com/vaelum/chords.git
cd chords

With Docker and HTTPS#

Tell Caddy your domain, then build and start the stack:

mkdir -p ~/.chords
echo 'chords.example.com' > ~/.chords/domain
python butler.py server build

This compiles the web app, builds the images and starts three containers: chords itself, a separate headless browser that the import opens pages in, and Caddy, which provisions a Let's Encrypt certificate for the domain in ~/.chords/domain. Without that file, Caddy does not start.

All data lives in ~/.chords: the database and secrets.json. Back it up with python butler.py server backup.

Without Docker#

pip install -r server/backend/requirements.txt
CHORDS_DATA_DIR=~/.chords python butler.py server run

The server listens on http://localhost:8000. The import's headless browser then runs in the same process, so install its Chromium once with python -m playwright install chromium if you want to import from links.

The first account#

The first start creates the database and an account named admin. Its password is the admin_passcode in ~/.chords/secrets.json, generated on the first start. To change it, edit the file; it is read at every login.

Every other account is made from an invite: as admin, open Admin · Invites, choose Generate invite link and send the link. Each link signs up one person.

Updating#

Pull the new version and run python butler.py server build again. The data in ~/.chords is kept. Signed-in apps notice the new version and offer to reload.

python butler.py --help lists every component and action.