ExpenseOwl

Why Create This? • Features • Screenshots
Installation • Usage • Contributing

ExpenseOwl is an extremely simple self-hosted expense tracking system with a modern monthly pie-chart visualization and cashflow showcase.

Why Create This?

There are a ton of amazing projects for expense tracking across GitHub (Actual, Firefly III, etc.). They're all incredible! I just don't find them fast and simple. They offer too many features I never use (like accounts or complex budgeting). Don't get me wrong! They're amazing when complexity is needed, but I wanted something dead simple that gives me a quick monthly look at my expenses. NOTHING else!

So, I created this project and I use it in my home lab for expenses. The primary intention is to track spending across your categories in a simplistic manner. No complications, searching, budgeting. This is not a budgeting app; it's for tracking.

Features

Core Functionality

• Quick expense/income add (only date, amount, and category are required)
• Single-user focused (mainly for a home lab deployment)
• Recurring transactions for both income and expenses
• Custom categories, currency symbols, and start date via app settings
• Optional tags for further classification
• Beautiful interface with both light and dark themes
• Self-contained binary and container image to ensure no internet interaction
• Multi-architecture Docker container with support for persistent storage
• PWA support for using the app on smartphone

Visualization

1. Main dashboard - category breakdown (pie chart) and cashflow indicator
   • Click on a category to exclude it from the pie chart; click again to add it back
   • Visualize the month's breakdown without considering some categories like Rent
   • Cashflow shows total income, total expenses, and balance (red or green based on +ve or -ve)
2. Table view for detailed expense listing
   • View monthly or all expenses chronologically and delete them (hold shift to skip confirm)
   • Use the browser to search for a name or tags if needed
   • Tags show up if at least one transaction uses it;
3. Settings page for configurations and additional features
   • Reorder, add, or remove custom categories
   • Select a custom currency symbol and a custom start date
   • Exporting data as CSV and import CSV from virtually anywhere

Progressive Web App (PWA)

The front end of ExpenseOwl can be installed as a Progressive Web App on desktop and mobile devices (i.e., the back end still needs to be self-hosted). To install:

• Desktop: Click the install icon in your browser's address bar
• iOS: Use Safari's "Add to Home Screen" option in the share menu
• Android: Use Chrome's "Install" option in the menu

Screenshots

Dashboard Showcase:

	Desktop View	Mobile View
Dark
Light

Expand this to see screenshots of other pages

	Desktop View	Mobile View
Table Dark
Table Light
Settings Dark
Settings Light

Installation

The recommended installation method is Docker. To run the container via CLI, use the following command:

docker run --rm -d \
  --name expenseowl \
  -p 8080:8080 \
  -v expenseowl:/app/data \
  tanq16/expenseowl:main

To use Docker compose, use this YAML definition:

services:
  expenseowl:
    image: tanq16/expenseowl:main
    restart: unless-stopped
    ports:
      - 5006:8080 # change 5006 to what you want to expose on
    volumes:
      - /home/tanq/expenseowl:/app/data # change dir as needed

git clone https://github.com/tanq16/expenseowl.git && \
cd expenseowl && \
go build ./cmd/expenseowl

Usage

Once deployed, use the web interface to do everything. Access it through your browser:

• Dashboard: http://localhost:8080/
• Table View: http://localhost:8080/table
• Settings: http://localhost:8080/settings

[!NOTE] This app does not include authentication, so deploy carefully. I don't want to add half-baked authentication, so use Authelia, or equivalent as needed. ExpenseOwl works well with a reverse proxy like Nginx Proxy Manager too and is intended for homelab use only.

Conventions

Since writing the app, I've found a ton of ways applications handle expenses. Release v4.0 solidifies the conventions I will continue to maintain the app in.

• Expenses are categorized by a -ve value, while income or reimbursement (designated by the Report as gain checkbox) are +ve
• Expense dates are stored as UTC strings in RFC3339 format, however, the frontend hides the time value from the user; users are meant to select a date, and the current local time is automatically added to the given date
• Future and recurring expenses extending into future dates are added immediately to the backend
• The primary way to use ExpenseOwl is to quick review the month's stats via the pie chart - this allows users to make a mental note and soft decision of where to spend money, without the effort of maintaining a budget
• Categories are meant to be used as a classification criteria - example, how much did I spend on food, groceries, and utilities, etc.
• Tags are optional and are meant to assign features and characteristics to expenses.

[!NOTE] While these conventions can change during the project's lifecycle, largely, the intention (stemming from the motivation to build ExpenseOwl) behind simple, manual, easy tracking will not change.

Configuration Options

With the exception of Data backends, all configuration of ExpenseOwl happens via the application UI. The list of all such options available via the settings page (/settings endpoint) is as follows:

• Category Settings:
• Currency Symbol:
  • This is a frontend symbol configuration on what symbol to use to show amount values
  • Each currency has its default behavior for using , or . as separators (and if it uses decimals or not)
• Start Date:
  • This is a custom day of the month from when the expenses will be displayed
  • Example: setting it to 5 means, expenses for each month will be counted from 5th to next month's 4th
• Recurring Transactions:
  • A recurring transaction can be for an expense or an income (gain)
  • Given a value for number of occurences and a start date, the app will add the transactions accordingly
  • Recurring transactions will be listed at the bottom of the page and can be edited/removed (all or future only transactions)
  • Recurring transactions allow similar options as normal expenses - category, tags, amount, name
• Theme Settings: supports light an