eleith
6b5bc5d7a5
3.0 KiB
Development and operations
Containers
Follow the quickstart. The containers target Linux/amd64 and require Docker host networking. From the repository root:
docker compose -f apps/web/docker-compose.dev.yml logs --follow
docker compose -f apps/web/docker-compose.dev.yml down
Use down without --volumes to preserve data. Restart after configuration changes;
rebuild after dependency or Dockerfile changes.
Compiled images use apps/web/docker-compose.yml instead. Stop development before
switching, configure the public URL, and use a trusted HTTPS proxy.
For direct local HTTP browsing, use development mode.
Host development
Use the Node and pnpm requirements in package.json. Install the pinned hledger executable, dependencies and shared packages:
sh tools/install-hledger.sh .cache/bin
export PATH="$PWD/.cache/bin:$PATH"
pnpm install --frozen-lockfile
pnpm build:packages
Run web and worker in separate terminals with the same explicit CONFIG_PATH:
CONFIG_PATH=/absolute/deployment/config/hledger-reports.yaml pnpm dev
CONFIG_PATH=/absolute/deployment/config/hledger-reports.yaml pnpm worker:dev
Use host-visible journal paths outside Docker. pnpm worker:inspect checks a
small fictional journal in a temporary directory; it does not prepare reports.
Checks
After review approval, run the affected package's tests, type check and lint. Build shared packages when their runtime code changes.
Browser tests need built apps, Chromium and its OS dependencies:
pnpm --filter @hledger-reports/web exec playwright install chromium
pnpm build
pnpm --filter @hledger-reports/web test:e2e --trace off
Leave PLAYWRIGHT_BASE_URL unset for isolated runs. The test server creates and
cleans up fictional data; never point browser tests at a personal deployment.
Private data and upgrades
- Keep live configuration, journals and runtime data out of Git and images.
- Compose shares
apps/web/data/between web and worker. It contains sensitive jobs and financial results and must be writable by container UID 1000. - Stop both services before backing up the whole data directory. Upgrade web and worker together; restore a consistent backup rather than downgrade a migrated database.
- Saved reports use SQLite generations. After updating web and worker together, explicitly prepare again; older financial JSON stays untouched but is no longer read.
- Do not delete data or reset volumes to fix unavailable reports. Request preparation explicitly and reload to inspect the result.
- Background maintenance removes eligible older balance-query jobs, not saved reports. Deletion is not secure erasure; SQLite and backups may retain data.
Automation
GitHub and Woodpecker definitions live in .github/workflows/ and .woodpecker/.
Both use owned fictional fixtures. Releases are manual;
publishing images does not deploy the app.