Sparky Budget is a compact open-source budgeting project that appeals to Docker hobbyists. Its SimpleFIN support is direct enough to understand end to end: configure the token, let the app claim it, persist the access URL and restart with the correct environment.
That simplicity is a strength. It also means operational details such as volume permissions, secret files and container restarts are part of the bank-sync setup.
Before you connect
Deploy Sparky Budget from the current repository instructions and confirm the app works with sample or manual data. Back up its database and configuration volume. Connect the supported bank in BankSync and create the SimpleFIN destination value using the current BankSync flow.
A setup token can be claimed once. If you rebuild the container without preserving its saved access URL, the original setup token cannot simply be pasted again. Generate a new one and follow the reset process.
Sparky Budget setup
Deploy the current container
Confirm persistent volumes and environment configuration.
Connect the bank in BankSync
Authorize the institution and verify selected accounts.
Create a SimpleFIN setup token
Copy it once from the current BankSync destination flow.
Set the application environment
Add the documented SimpleFIN value without committing it to source control.
Start or restart Docker
Allow Sparky Budget to claim the token and save the access URL.
Verify account discovery
Compare account identity, type, currency and balances.
Run a second sync
Confirm records are idempotent and the persistent volume survives restart.
The reset path
Sparky Budget’s repository documents deleting access_url.txt, generating a new setup token, updating .env and restarting Docker. Use that sequence only when replacing or repairing the connection. Do not delete the file casually; it is the credential the application needs for future reads.
Secure the volume
Restrict host filesystem permissions, encrypt the disk and backups, and do not publish the configuration volume through a file-sharing service. Redact the access URL from logs. If the repository includes debug settings, disable raw financial payload logging in production.
Data quality
Check the first import with a small account. Verify deposits, purchases, transfers and a current balance. If the app categorizes automatically, separate source import errors from category rules; a correct transaction can still land in the wrong budget category.
Sparky Budget verification
| Stage | What to do | Check |
|---|---|---|
| Volume | Configuration persists across restart | `access_url.txt` remains available |
| Secret | Not committed or logged | Host permissions are restrictive |
| Accounts | Remote IDs map once | No duplicate local account |
| Transactions | Second sync adds only new records | Stable IDs work |
| Balance | Deposit and liability signs are correct | Matches known source balance |
| Reset | Fresh token only when replacing | Old token is not retried |
Test the container lifecycle as well as the data.
Troubleshooting
If the token appears invalid, assume it may already be claimed and create a fresh one after preserving logs and the current volume. If the app works until restart, inspect Docker mounts and ownership. If data is stale, compare BankSync/provider freshness with the app’s last fetch before replacing credentials.
For contributors, add tests around missing access files, already-claimed tokens, pending-to-posted updates and duplicate transaction IDs. These cases matter more than adding another chart.