wtandClaude Opus 5.5
10272f3851
CI / Rust (fmt / clippy / test / build) (push) Successful in 1m41s
CI / HTTP/JSON reference + SQLite persistence (push) Successful in 1m16s
CI / Rust (fmt / clippy / test / build) (pull_request) Successful in 47s
CI / HTTP/JSON reference + SQLite persistence (pull_request) Successful in 1m34s
The Go implementation is preserved in the v1.0.0 tag. Its observable behaviour stays the API reference: responses recorded from the Go server live in tools/compatibility_expected.txt, and tools/compatibility.py now compares the Rust server against them (--update re-records after an intentional change). The Go SQLite schema is frozen in tests/fixtures/go_schema_v1.sql for the existing-database test. Move the web client from internal/httpapi/web to web/, drop the Go CI job and Go version pin, and update README, AGENTS.md and docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
93 lines
5.3 KiB
Markdown
93 lines
5.3 KiB
Markdown
# Deployment
|
|
|
|
## Runtime and configuration
|
|
|
|
The production executable is the Rust server, built with `cargo build --locked
|
|
--release`. SQLite is bundled into the executable. The original Go implementation
|
|
was removed after v1.0.0; the `v1.0.0` tag still contains its sources for the
|
|
migration and rollback below (`go build -o balance-server-go ./cmd/balance-server`).
|
|
|
|
The Dockerfile uses a Rust 1.90 Debian Bookworm builder and a Debian Bookworm slim
|
|
runtime, running as the unprivileged `balance` user. The image embeds the existing
|
|
web client and uses no separate frontend process. Build dependencies and SQLite
|
|
are compiled at image build time.
|
|
The numeric identity remains UID 100 / GID 101, matching the original Alpine Go
|
|
image, so existing volume permissions are preserved across the switch.
|
|
|
|
The image is multi-platform: `linux/amd64`, `linux/arm64` and `linux/arm/v7`
|
|
(armhf) are published under the same tag, and `docker pull` selects the matching
|
|
one. The builder stage runs on the build machine's platform and cross-compiles
|
|
Rust (with GCC cross compilers for bundled SQLite), so only the runtime stage
|
|
needs QEMU. Build all platforms locally with a `docker-container` buildx builder:
|
|
`docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 .`
|
|
|
|
`docker compose up -d --build` publishes **http://localhost:8123** (host 8123,
|
|
container 8080). `GET /health` is the liveness endpoint. Direct binary execution
|
|
uses `:8080` by default. Place a TLS reverse proxy in front of the published port
|
|
for remote access; pass `X-Forwarded-Proto: https` to enable Secure session cookies.
|
|
|
|
| Variable | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `BALANCE_ADDR` | `:8080` | HTTP listen address |
|
|
| `BALANCE_DB_PATH` | `./data/balance.db` | SQLite file; Docker uses `/data/balance.db` |
|
|
| `BALANCE_JWT_SECRET` | required | At least 32 characters; retain across migration |
|
|
| `BALANCE_ACCESS_TTL` | `15m` | Go-style duration for access tokens |
|
|
| `BALANCE_REFRESH_TTL` | `720h` | Go-style duration for refresh tokens |
|
|
| `BALANCE_ALLOW_REGISTRATION` | `true` | Enable creation of accounts |
|
|
| `BALANCE_CORS_ORIGINS` | empty | Comma-separated allowed browser origins |
|
|
|
|
Inject secrets through the deployment environment or `.env`; never put them in
|
|
images or source control. Compose preserves the existing named `balance-data`
|
|
volume mounted at `/data`. Keep that volume and its project name when upgrading.
|
|
|
|
## Go to Rust migration
|
|
|
|
1. Build and validate the Rust binary/image before stopping production. Retain the
|
|
previous Go executable/image and exact environment for rollback.
|
|
2. Stop the Go service and confirm no other process writes its SQLite database.
|
|
3. Back up the entire database directory, including `balance.db` and any
|
|
`balance.db-wal`/`balance.db-shm` files. Protect the backup as financial data.
|
|
Record the existing environment securely, especially `BALANCE_JWT_SECRET`.
|
|
4. Start Rust with the **same database path/volume and JWT secret**. The schema is
|
|
unchanged: startup creates missing tables and indexes without rewriting
|
|
existing accounts, records, change sequences or refresh-token hashes.
|
|
5. Check `/health`, login with an existing account, refresh an existing session,
|
|
and sync a device with its saved cursor. Verify another device receives edits
|
|
and tombstones. Inspect error rates without logging credentials or tokens.
|
|
|
|
The existing Argon2id password hashes, HS256 JWT claims, hashed refresh tokens,
|
|
RFC3339 timestamps, entity versions and global change sequences are shared with
|
|
Go. No export/import, cursor reset, account recreation or forced sign-out is
|
|
required. Do not start both implementations against the same database at once.
|
|
|
|
## Rollback
|
|
|
|
Stop Rust first. Start the retained Go executable/image with the same current
|
|
database directory and secret. Rust-written accounts, password hashes, refresh
|
|
sessions, records, tombstones and cursors remain readable by Go. Check health,
|
|
login, refresh and sync again. Before the Go sources were removed, the
|
|
compatibility suite verified takeover and rollback in both directions; Rust still
|
|
writes the same schema (`tests/fixtures/go_schema_v1.sql`).
|
|
|
|
For database corruption or an unrelated failed migration, stop all writers before
|
|
restoring the complete backup directory. Restoring an older backup discards
|
|
changes after that backup and may require clients to resynchronize; prefer normal
|
|
binary rollback against the current database when it is healthy. Never overwrite
|
|
an active database or delete a Compose volume as part of an upgrade.
|
|
|
|
## Validation and operations
|
|
|
|
Before release run `cargo test --locked`, `cargo build --locked --release`,
|
|
and `python3 tools/compatibility.py --binary target/release/balance-server`.
|
|
The suite uses temporary databases and loopback listeners, compares
|
|
API/errors/security headers/assets with the recorded Go reference, tests browser
|
|
cookies, pagination, LWW, tombstones, concurrent pushes, token expiration, refresh
|
|
rotation, rate limiting, and SQLite persistence across restarts.
|
|
|
|
Keep regular encrypted backups with retention and restore drills. Monitor HTTP
|
|
5xx, sync errors, authentication failures, latency, database/change-log growth
|
|
and free disk space. The in-memory limiter allows 30 registration/login/refresh
|
|
attempts per remote IP per minute and resets on restart; use proxy controls when
|
|
operating a public service. Application logs must never include passwords,
|
|
Authorization headers or tokens.
|