1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
|
# CLAUDE.md
Single bash script, `firefly-update`, that updates a Firefly III instance on
Debian. See README.md for usage; this file is the non-obvious context.
## Hard-won gotchas (do not relearn these)
- **Install from the GitHub release zip, never `composer create-project`.** The
composer/Packagist dist ships source only, no compiled frontend bundles
(`public/v1/js/app.js`, `app_vue.js`, ...). A composer install looks fine but
the UI is broken: no graphs, `404 /v1/js/app.js`, and the v2 error/login
pages throw `Vite manifest not found (public/build/manifest.json)` as a
secondary symptom. The zip is prebuilt and is the supported artifact.
- **Release tag carries a leading `v`** (`v6.6.5`). Asset name is
`FireflyIII-<tag>.zip` with the `v` included. `--version` is normalized so
both `6.6.5` and `v6.6.5` work; don't reintroduce a double-`v` bug.
- **Passport OAuth migration collision.** Laravel Passport renames its
migration files between versions, so a carried-over DB has the `oauth_*`
tables while the new filenames look pending; a naive `migrate` dies with
`table "oauth_auth_codes" already exists` (then `oauth_device_codes`, ...).
The script reconciles the `migrations` ledger before migrating (records
already-present tables, lets missing ones create). Do NOT "fix" a collision
by dropping tables, it is whack-a-mole and can lose
`oauth_personal_access_clients`.
- **The Vite/`public/build` error is a red herring for graphs.** It only fires
on the v2 error and login pages. Graphs breaking = missing `public/v1/js`
bundles (see the zip point above), a different cause.
- **Upgrade artisan sequence follows the official self-managed docs**:
`migrate --seed`, `cache:clear`, `view:clear`, `firefly-iii:upgrade-database`,
`firefly-iii:laravel-passport-keys`. Use `firefly-iii:laravel-passport-keys`,
NOT `passport:install`. We add `--force` (non-interactive) and the oauth
reconcile before migrate. Docs also confirm composer create-project is no
longer recommended.
- **Release `.sha256` format** is `<hash> *FireflyIII-<tag>.zip` (BSD-style,
space then `*`); `cut -d' ' -f1` gets the hash. The script verifies it when
`sha256sum` is available, and validates the extracted tree before swapping.
## Conventions
- Config via env vars (`WORKDIR`, `INSTANCE`, `BACKUPDIR`), matching the
existing style; no new CLI flags unless asked.
- Keep it a single file. `set -euo pipefail` + `ERR` trap are load-bearing:
the script must abort before the live swap on any failure and never leave a
half-update looking successful.
- Any change to the install/migrate flow: test the download+extract and the
migrate path before claiming it works. The script touches a live personal
finance instance; a bad run is not cheap.
## Testing without a target machine
There is no Firefly instance in this repo. Test URL construction and
download/extract against the real GitHub releases (the asset URLs are public);
the artisan/migrate steps can only be exercised on the actual host.
|
