fafd763d99
All checks were successful
Build and Test / build-and-test (push) Successful in 34s
build.yml now only stages the binary into ~/hsa-app/releases on tag (no symlink swap or restart). Activation is a separate workflow_dispatch workflow (deploy.yml) the user triggers from the Forgejo Actions tab, passing the tag to point the symlink at and restart. Update INSTALL.md to describe the stage/activate split. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
# Deploying hsa-app
|
|
|
|
The app runs as a **user systemd service** (no sudo). Deployment is two steps:
|
|
|
|
1. **Stage (automatic on tag)** — pushing a git tag builds + tests, then CI
|
|
copies the binary into `~/hsa-app/releases/hsa-app-V<tag>/hsa`. Nothing goes
|
|
live yet.
|
|
2. **Activate (manual button)** — run the **Deploy** workflow from the Forgejo
|
|
Actions tab ("Run workflow"), entering the tag to activate. It points the
|
|
`~/hsa-app/hsa` symlink at that release and restarts the service.
|
|
|
|
The symlink decouples "what's on disk" from "what's running," so activation and
|
|
rollback are just a symlink repoint + restart.
|
|
|
|
## Layout on the host
|
|
|
|
Mutable state (DB, env, config) lives at the top of `~/hsa-app/` and survives
|
|
every deploy. Only the binaries live under `releases/`.
|
|
|
|
```
|
|
~/hsa-app/
|
|
hsa_app.sh # launcher: sources env file, exec's the binary
|
|
hsa_app.env # environment (KEY=VALUE)
|
|
config.json
|
|
hsa.db, hsa.db-shm, hsa.db-wal # SQLite state
|
|
releases/
|
|
hsa-app-V0.0.0a0/hsa
|
|
hsa-app-V0.0.1/hsa
|
|
hsa -> releases/hsa-app-V0.0.1/hsa # current symlink, swapped on deploy
|
|
```
|
|
|
|
## The current symlink
|
|
|
|
Create/repoint it **from inside `~/hsa-app`** so the relative target resolves
|
|
against the link's own directory (running `ln -s` from `~` produces a broken
|
|
link that points at `~/hsa-app/hsa-app/...`):
|
|
|
|
```bash
|
|
cd ~/hsa-app
|
|
chmod +x releases/hsa-app-V<tag>/hsa
|
|
ln -sfn releases/hsa-app-V<tag>/hsa hsa # -f replace, -n don't follow existing link
|
|
ls -l hsa # target must resolve (not broken)
|
|
```
|
|
|
|
This same `ln -sfn` + `chmod +x` is what the CI deploy step runs on each tag.
|
|
|
|
## Install the service (once)
|
|
|
|
Save [hsa_app.service](hsa_app.service) to `~/.config/systemd/user/hsa_app.service`,
|
|
then:
|
|
|
|
```bash
|
|
loginctl enable-linger "$USER" # run the service without an active login session
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now hsa_app
|
|
systemctl --user status hsa_app
|
|
journalctl --user -u hsa_app -f # follow logs
|
|
```
|
|
|
|
### Why these choices
|
|
|
|
- **User service** (`systemctl --user`) — no sudo, matches the home-dir deploy.
|
|
`enable-linger` lets it start at boot / stay up without an interactive login.
|
|
- **`Type=exec`** — `hsa_app.sh` ends in `exec "$BIN"`, so the binary becomes the
|
|
unit's main process; signals and exit codes propagate correctly.
|
|
- **`WorkingDirectory=%h/hsa-app`** — relative paths in the env file resolve here.
|
|
The launcher's comment recommends absolute paths for `DB_PATH` / `STORAGE_DIR` /
|
|
`BACKUP_DIR` / `CONFIG_PATH`; either works.
|
|
- **ExecStart passes the env file as `$1`** — matches `hsa_app.sh`'s first-arg
|
|
precedence, so no `/etc/hsa-app/...` file is needed. `%h` expands to the home dir.
|
|
- The launcher defaults its binary to `./hsa` next to itself (`~/hsa-app/hsa`, the
|
|
symlink), so a restart after a symlink swap runs the new release automatically.
|
|
|
|
## Deploy a tagged release
|
|
|
|
Pushing a tag stages the binary automatically. To activate it, open the repo's
|
|
**Actions → Deploy** workflow, click **Run workflow**, and enter the tag (e.g.
|
|
`0.0.0a1`). To activate from the host instead:
|
|
|
|
```bash
|
|
cd ~/hsa-app
|
|
chmod +x releases/hsa-app-V<tag>/hsa
|
|
ln -sfn releases/hsa-app-V<tag>/hsa hsa
|
|
systemctl --user restart hsa_app
|
|
```
|
|
|
|
## Roll back
|
|
|
|
Every release stays under `releases/`, so rollback is a symlink repoint:
|
|
|
|
```bash
|
|
cd ~/hsa-app
|
|
ln -sfn releases/hsa-app-V<old-tag>/hsa hsa
|
|
systemctl --user restart hsa_app
|
|
```
|