eleith
6b5bc5d7a5
ci/woodpecker/pr/db Pipeline was successful
ci/woodpecker/pr/hledger Pipeline was successful
ci/woodpecker/pr/snapshots Pipeline was successful
ci/woodpecker/pr/web Pipeline was successful
ci/woodpecker/pr/worker Pipeline was successful
ci/woodpecker/push/db Pipeline was successful
ci/woodpecker/push/hledger Pipeline was successful
ci/woodpecker/push/snapshots Pipeline was successful
ci/woodpecker/push/web Pipeline was successful
ci/woodpecker/push/worker Pipeline was successful
72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
# Development and operations
|
|
|
|
## Containers
|
|
|
|
Follow the [quickstart](../README.md#run-locally). The containers target Linux/amd64
|
|
and require Docker host networking. From the repository root:
|
|
|
|
```sh
|
|
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](authentication.md#trusted-proxy).
|
|
For direct local HTTP browsing, use development mode.
|
|
|
|
## Host development
|
|
|
|
Use the Node and pnpm requirements in [package.json](../package.json). Install the
|
|
pinned hledger executable, dependencies and shared packages:
|
|
|
|
```sh
|
|
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`:
|
|
|
|
```sh
|
|
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](philosophy.md#review), 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:
|
|
|
|
```sh
|
|
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](../.changeset/README.md);
|
|
publishing images does not deploy the app.
|