README
¶
Liturgist
Liturgist helps a church plan its services: the order of worship, songs and Scripture readings, a review step, and publishing the result to the people who serve. It is free software for a single church to run on its own computer, with an English and Indonesian interface (English first).
Status: before version 1.0. The pilot church is GKY Citragarden.
Quick start
You need Docker and Git. There is no published image yet (it comes with the first release), so build it from the source. In a terminal:
git clone https://github.com/brightfellow-net/liturgist.git
cd liturgist
docker build -t liturgist:local .
docker run -d --name liturgist --restart unless-stopped -p 127.0.0.1:8080:8080 \
-v liturgist-data:/data -e LITURGIST_BASE_URL=http://localhost:8080 liturgist:local
docker logs liturgist
The build takes a few minutes the first time. --restart unless-stopped starts it again after a reboot of the computer.
Open the setup link shown in the log to create your church and its first administrator. That is a trial on one computer. For a real installation, with HTTPS and backups, follow a guide below.
Install
| Guide | For |
|---|---|
| Docker | any system with Docker, the simplest |
| Linux | a Linux server or Raspberry Pi, with systemd |
| Windows | a Windows PC or server, as a service |
Then add HTTPS: built in (Let's Encrypt, when the server has a public address), Caddy, nginx, Cloudflare Tunnel or Tailscale.
Look after it
- Backup and restore: nightly backups are automatic; keep a copy away from the server, and try a restore once.
- Upgrading, including how to verify a download.
- Configuration: every setting.
For developers
Go server (chi, Huma, sqlx; SQLite or PostgreSQL) and a React app (Vite, TanStack Query, Tailwind). The product is described in docs/SPEC.md and the design in docs/impl/.
make build # generates the API client, builds the web app, then bin/liturgist
make test # Go and web unit tests
make e2e # browser tests
Licence: Apache-2.0 (LICENSE).
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
argon2pw
Package argon2pw is the argon2id app.PasswordHasher (03 §3).
|
Package argon2pw is the argon2id app.PasswordHasher (03 §3). |
|
entitlements/unlimited
Package unlimited is the community Entitlements: everything allowed, no limits (04 §8).
|
Package unlimited is the community Entitlements: everything allowed, no limits (04 §8). |
|
eventbus/memory
Package memory is the community EventBus: subscribers in the same process (04 §7).
|
Package memory is the community EventBus: subscribers in the same process (04 §7). |
|
httpapi
Package httpapi holds the HTTP adapter: middleware for sessions, client IP and CSRF, the Huma operations, and the mapping of errors to problems (01 §10).
|
Package httpapi holds the HTTP adapter: middleware for sessions, client IP and CSRF, the Huma operations, and the mapping of errors to problems (01 §10). |
|
images
Package images turns an uploaded logo into the PNG that is stored (15 §2, L-2): the real format is read from the bytes, the size is checked before the pixels are decoded, the image is scaled down to fit a square and written as a new PNG, which drops metadata and anything else hidden in the file.
|
Package images turns an uploaded logo into the PNG that is stored (15 §2, L-2): the real format is read from the bytes, the size is checked before the pixels are decoded, the image is scaled down to fit a square and written as a new PNG, which drops metadata and anything else hidden in the file. |
|
importers/chordpro
Package chordpro reads ChordPro files (08 §4.3).
|
Package chordpro reads ChordPro files (08 §4.3). |
|
importers/openlyrics
Package openlyrics reads OpenLyrics song files (OpenLP, 08 §4.2).
|
Package openlyrics reads OpenLyrics song files (OpenLP, 08 §4.2). |
|
importers/paste
Package paste splits pasted lyrics into sections (08 §4.1).
|
Package paste splits pasted lyrics into sections (08 §4.1). |
|
notify/copyshare
Package copyshare is the community Notifier: nothing is sent automatically; people copy and share messages themselves (04 §7).
|
Package copyshare is the community Notifier: nothing is sent automatically; people copy and share messages themselves (04 §7). |
|
sqlstore
Package sqlstore is the shared SQL persistence adapter for SQLite and PostgreSQL (02).
|
Package sqlstore is the shared SQL persistence adapter for SQLite and PostgreSQL (02). |
|
sqlstore/sqlstoretest
Package sqlstoretest provides migrated databases for tests (02 §6).
|
Package sqlstoretest provides migrated databases for tests (02 §6). |
|
storage/localfs
Package localfs is the community Storage: files in a local folder, <DataDir>/files (04 §7).
|
Package localfs is the community Storage: files in a local folder, <DataDir>/files (04 §7). |
|
sysclock
Package sysclock is the production app.Clock.
|
Package sysclock is the production app.Clock. |
|
tenancy
Package tenancy holds the community tenant resolver and URL builder (04 §3, §4).
|
Package tenancy holds the community tenant resolver and URL builder (04 §3, §4). |
|
ulidgen
Package ulidgen is the production app.IDGenerator.
|
Package ulidgen is the production app.IDGenerator. |
|
Package app holds use cases and the ports they depend on (02 §2).
|
Package app holds use cases and the ports they depend on (02 §2). |
|
cmd
|
|
|
liturgist
command
Command liturgist is the community edition server and CLI.
|
Command liturgist is the community edition server and CLI. |
|
Package domain holds entities and rules.
|
Package domain holds entities and rules. |
|
commonpw
Package commonpw holds the common-password lists (03 §3): the NCSC top 100,000 (from SecLists, MIT licence; see LICENSE-SecLists) and a curated Indonesian / church list.
|
Package commonpw holds the common-password lists (03 §3): the NCSC top 100,000 (from SecLists, MIT licence; see LICENSE-SecLists) and a curated Indonesian / church list. |
|
internal
|
|
|
backup
Package backup writes and reads the backup archive of 14 §3: one zip with manifest.json, liturgist.db and files/….
|
Package backup writes and reads the backup archive of 14 §3: one zip with manifest.json, liturgist.db and files/…. |
|
envconfig
Package envconfig reads the LITURGIST_* environment variables (01 §5).
|
Package envconfig reads the LITURGIST_* environment variables (01 §5). |
|
logging
Package logging builds the slog logger with redaction of secrets (01 §9).
|
Package logging builds the slog logger with redaction of secrets (01 §9). |
|
Package migrations embeds the SQL migrations; both folders must hold the same versions (02 §5).
|
Package migrations embeds the SQL migrations; both folders must hold the same versions (02 §5). |
|
Package server is the composition root: it wires adapters to the use cases and serves the HTTP API and web app (01 §7).
|
Package server is the composition root: it wires adapters to the use cases and serves the HTTP API and web app (01 §7). |
|
Package web embeds the built frontend (web/dist).
|
Package web embeds the built frontend (web/dist). |
Click to show internal directories.
Click to hide internal directories.