Ledgerly

A personal finance app for tracking bills, where they're paid from, projected account balances, loans and amortization.

Ledgerly is released under the MIT License.

Installing on a server (Beta and Production)

Ledgerly runs in Docker on a Linux server. There are two release channels, each installed separately with its own port, database and encryption keys, so trying out Beta never touches your real data:

You need Docker with the Compose plugin. Install or update with one command:

curl -fsSL https://raw.githubusercontent.com/007darkmatter5/ledgerly/main/deploy/install.sh | sudo bash -s -- beta
curl -fsSL https://raw.githubusercontent.com/007darkmatter5/ledgerly/main/deploy/install.sh | sudo bash -s -- production

Each run downloads the newest build for that channel, stops the old container, backs up the database (the last 10 backups are kept in backups/), starts the new version, and waits until it reports healthy. Beta shows a Beta badge in the app so you can tell them apart.

Options (the port and bind address are remembered for later updates):

install.sh beta --port 8006                   # a different port
install.sh production --bind 127.0.0.1        # only reachable locally, e.g. behind a reverse proxy
install.sh production --version 1.0.41        # install (or roll back to) a specific version

Your own settings go in /opt/ledgerly/<channel>/ledgerly.env (for example ASPNETCORE_FORWARDEDHEADERS_ENABLED=true behind a reverse proxy that handles HTTPS). Keep the keys folder with the install: it holds the encryption keys for sign-in cookies and the saved email password. Back it up separately from data.

Rolling back: run the script with --version <previous version> (listed on the Releases page and in the backup folder names). If the newer version already upgraded the database, stop the container and copy the matching backup back into data/ first.

Unraid

Production from Community Apps: in the Apps tab, search for Ledgerly and click Install. The defaults work as they are: port 5005, data in /mnt/user/appdata/ledgerly/data, encryption keys in /mnt/user/appdata/ledgerly/keys, running as nobody:users (99/100). Open the WebUI and create the first account (it becomes the admin). When a new production release is out, the Docker tab shows update ready. The template lives in 007darkmatter5/unraid-templates.

Beta: use deploy/unraid/docker-compose.yml with the Docker Compose Manager plugin (install it from Apps):

1. Docker tab → Compose section → Add New Stack, name it ledgerly-beta.
2. On the stack's gear icon, choose Edit Stack → Compose File, paste the file's contents and save.
3. Click Compose Up. Open http://<unraid-ip>:5006 and create the first account (it becomes the admin).

It's a single container that stores everything in /mnt/user/appdata/ledgerly-beta (data/ for the database, keys/ for encryption keys) and uses the server's time zone. On start it gives those folders to PUID/PGID (99/100, nobody:users, like other Unraid containers) and then runs Ledgerly as that user, not root.

• Update to the newest beta: on the stack, Update Stack (pulls :beta and recreates the container). Database changes run automatically on start.
• Back up before updating: Ledgerly doesn't make its own backup here. Use the Appdata Backup plugin (it stops containers for a consistent copy), or stop the stack and copy /mnt/user/appdata/ledgerly-beta.
• Beta alongside Production: the beta stack uses its own port (5006) and appdata folder (ledgerly-beta), so both can run at once without sharing data.
• Pin a version: replace :beta with a specific tag from the Releases page, e.g. :1.0.12-beta.

Release workflow

1. Commit changes to the beta branch and push. GitHub Actions runs the tests, publishes the Beta image and creates a pre-release (e.g. v1.0.12-beta).
2. Update Beta on the server and try it out.
3. When you're happy, merge beta into main and push. That publishes the Production image and a release (e.g. v1.0.13).
4. Update Production on the server.

Version numbers are <major.minor from the VERSION file>.<build number>; edit VERSION to start a new series (e.g. 1.1).

Running from source

Requires the .NET 10 SDK.

dotnet run --project src/Ledgerly

Then open http://localhost:5005 and create an account. Data is stored in src/Ledgerly/App_Data/ledgerly.db.

Run the tests with dotnet test.

Admins

The first account created is Ledgerly's admin. (If accounts already existed before admins were added, the earliest one becomes admin automatically.) Admins find an Administration section under account menu → Account settings, where they can:

• Email server: set up email for password resets.
• Users & sign-ups: turn new sign-ups on or off, and make other accounts admins.
• Backup & restore: download everything in the install, or restore a backup (see Moving to another server).

Admins can't see anyone else's bills, accounts or loans in the app. A backup file, though, contains every user's data, so only make people admins you'd trust with it. There's always at least one admin: the last admin can't be removed or delete their account until someone else is made an admin.

Tip for a household install: once everyone who needs an account has created one, turn off new sign-ups.

Moving to another server

Use account menu → Account settings → Backup & restore (admins only).

1. On the old install, click Download backup. The file holds every account (with passwords and two-factor settings), all bills, accounts, loans and payment history, and the admin settings, including the email server password. Keep it private.
2. Install Ledgerly on the new server and create an account (it becomes the admin for now).
3. On the new install, open Backup & restore, choose the file, tick the confirmation box and click Restore backup. Everything in the new install is replaced, and everyone is signed out.
4. Sign in with your account from the old install.

Things to know:

• The new install must run the same or a newer version than the old one. Older backups are upgraded when restored; a backup from a newer version (for example Beta restored into Production) is refused until you update.
• Before replacing anything, Ledgerly saves a copy of the current database to backups/before-restore-<date>.db next to the database (the last 5 are kept). To undo a restore, restore a backup you downloaded earlier, or stop Ledgerly, delete ledgerly.db-wal and ledgerly.db-shm if they exist, and copy that file over ledgerly.db.
• Settings from environment variables or ledgerly.env (port, culture, reverse proxy, email configuration) aren't in the backup. Set them on the new server.
• On Unraid (or any Docker host) you can also stop the container and copy the whole appdata folder (data and keys) to the new server instead.

Setting up email

Email is optional. Without it everything works except Forgot password?, which stays hidden until an email server is set up.

Ledgerly sends mail through any SMTP server: your email provider, your own domain's mail server, or a sending service.

1. Get your SMTP details

You need a server address, port, username, password and a "from" address. Common setups (check your provider's current documentation, since these change):

2. Enter them in Ledgerly

Sign in as an admin and go to account menu → Account settings → Email server. Fill in the form and click Send test email & save. Ledgerly sends a test message to your address with the new settings and only saves them if it goes through. If your server accepts mail but the test can't reach it from here, Save without testing appears after a failed test.

• The password is stored encrypted using ASP.NET Core Data Protection. The encryption keys are kept apart from the database (your Windows user profile when running from source; the install's keys folder on a server), so a copy of ledgerly.db alone doesn't reveal it. It's never shown again after saving; leave the field blank to keep it.
• If the keys are lost (for example, moving to another computer without the keys folder), the saved password can't be decrypted. The page will say so; just enter it again.
• Ledgerly's address is used for links inside emails. Set it to the address people type to open Ledgerly (for example http://localhost:5005, or another computer's address on your network).

Alternative: configuration files or environment variables

Email settings can also come from configuration. On a server, put them in the install's ledgerly.env file (it has commented examples) and run docker compose up -d in that folder. Configuration takes priority: when it sets Email:Host, the Email server page becomes read-only.

On your own computer, use .NET user secrets (stored in your Windows profile, only read by dotnet run's Development environment):

cd src/Ledgerly
dotnet user-secrets set "Email:Host" "smtp.gmail.com"
dotnet user-secrets set "Email:Port" "587"
dotnet user-secrets set "Email:Security" "StartTls"
dotnet user-secrets set "Email:Username" "you@gmail.com"
dotnet user-secrets set "Email:Password" "your app password"
dotnet user-secrets set "Email:FromAddress" "you@gmail.com"
dotnet user-secrets set "Email:PublicBaseUrl" "http://localhost:5005"

Remove them with dotnet user-secrets clear. When hosting elsewhere, use environment variables with double underscores instead: Email__Host, Email__Password, and so on. Never put the password in appsettings.json.

Troubleshooting