Implementing plain-text accounting with hledger on a self-hosted synology nas to track homelab infrastructure costs and energy usage

Why I Started Tracking Homelab Costs in Plain Text

I run a homelab on Synology NAS and Proxmox. After a year of adding drives, upgrading RAM, and spinning up new containers, I had no clear picture of what this hobby actually cost me. My electricity bill kept climbing, but I couldn't tell how much was the homelab versus everything else in the house.

I needed something that could:

• Track one-time hardware purchases
• Record monthly electricity costs per device
• Show me trends over time
• Work entirely on my own infrastructure
• Use plain text files I could version control

I looked at spreadsheets first. They work, but formulas break, sheets multiply, and sharing data between files gets messy. I wanted something more structured but still human-readable.

That's when I found hledger, a plain-text accounting tool. It reads journal files written in a simple format and generates reports. No database, no web interface required, just text files and a command-line tool.

My Synology Setup

I run DSM 7.2 on a Synology DS920+. I already had Docker installed through Container Manager for other services. My plan was to run hledger in a container and store the journal files in a shared folder that I could edit from any device.

I created a shared folder called accounting with these subdirectories:

• journals/ - where I keep my .journal files
• reports/ - for generated HTML reports
• scripts/ - automation helpers

I gave my main user account read/write access to this folder.

Running hledger in Docker

There's an official hledger Docker image, but I wanted something I could customize. I built my own minimal container using Alpine Linux as the base.

Here's the Dockerfile I used:

FROM alpine:3.19

RUN apk add --no-cache hledger hledger-web

WORKDIR /data

EXPOSE 5000

CMD ["hledger-web", "--serve", "--host=0.0.0.0", "--port=5000", "--base-url=http://nas.local:5000"]

I built this on my Synology using SSH:

docker build -t hledger-local .

Then I created a docker-compose file in my accounting folder:

version: '3.8'

services:
  hledger:
    image: hledger-local
    container_name: hledger
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - ./journals:/data
    environment:
      - TZ=America/New_York

I started it with docker-compose up -d. The web interface appeared at http://nas.local:5000, but I rarely use it. Most of my work happens in the text files.

How I Structure My Journal Files

Plain-text accounting uses double-entry bookkeeping. Every transaction has at least two entries that balance to zero. It sounds complicated, but once you see it in practice, it's straightforward.

I created a main file called homelab.journal with this structure:

; Homelab Infrastructure Accounting
; Started: 2024-01-01

; === ACCOUNTS ===
account assets:cash                    ; Money I have
account expenses:hardware              ; Physical purchases
account expenses:electricity           ; Power costs
account expenses:services              ; Domains, VPS, etc
account equity:opening                 ; Starting balance

; === OPENING BALANCE ===
2024-01-01 * Opening Balance
    assets:cash                        $5000.00
    equity:opening

; === TRANSACTIONS ===

The account definitions aren't required, but they help me remember my structure. The opening balance represents money I'm willing to spend on homelab stuff—it's conceptual, not a real bank account.

Recording Hardware Purchases

When I bought a 4TB WD Red drive in January, I added:

2024-01-15 * WD Red 4TB Drive
    expenses:hardware:storage          $89.99
    assets:cash

The asterisk marks it as cleared. The second line (assets:cash) has no amount because hledger infers it must be -$89.99 to balance.

I tag larger purchases with metadata:

2024-02-03 * Crucial 32GB DDR4 RAM
    ; serial: CT32G4SFD832A
    ; installed: proxmox-host
    expenses:hardware:memory           $124.50
    assets:cash

Comments starting with semicolons let me record serial numbers, where I installed things, or warranty dates.

Tracking Electricity Costs

This was trickier. I wanted to track power usage per device, but I didn't have individual smart plugs on everything. I measured what I could and estimated the rest.

I used a Kill-A-Watt meter to measure:

• Synology DS920+: ~35W average
• Proxmox host (old desktop): ~85W idle, ~140W under load
• Network switch: ~12W
• Cable modem: ~8W

I assumed the Proxmox host averaged 100W over a month (mostly idle, occasional heavy loads).

My electricity rate is $0.14 per kWh. I calculated monthly costs:

• Synology: 35W × 24h × 30d = 25.2 kWh → $3.53/month
• Proxmox: 100W × 24h × 30d = 72 kWh → $10.08/month
• Switch: 12W × 24h × 30d = 8.64 kWh → $1.21/month
• Modem: 8W × 24h × 30d = 5.76 kWh → $0.81/month

I record these monthly:

2024-01-31 * January Electricity - Synology
    expenses:electricity:synology      $3.53
    assets:cash

2024-01-31 * January Electricity - Proxmox
    expenses:electricity:proxmox       $10.08
    assets:cash

2024-01-31 * January Electricity - Network
    expenses:electricity:network       $2.02
    assets:cash

I know these aren't perfectly accurate. The Proxmox host varies based on what I'm running. But close enough is better than nothing, and I can refine the numbers if I add more monitoring later.

Recurring Costs

I also track domain renewals and the occasional VPS I use for off-site backups:

2024-03-12 * Domain Renewal - vipinpg.com
    expenses:services:domains          $15.00
    assets:cash

2024-03-01 * Hetzner VPS - Backup Server
    ; monthly backup storage
    expenses:services:vps              $4.50
    assets:cash

Generating Reports

The real value comes from querying this data. I use hledger's command-line tools to generate reports.

Total Spending by Category

hledger -f homelab.journal balance expenses

Output:

            $1,247.83  expenses
              $214.49    electricity
               $42.36      network
              $120.72      proxmox
               $51.41      synology
              $978.84    hardware
              $124.50      memory
               $89.99      storage
              $764.35      other
               $54.50    services
               $30.00      domains
               $24.50      vps

This tells me I've spent the most on hardware (expected), but electricity is adding up faster than I thought.

Monthly Electricity Trends

hledger -f homelab.journal register expenses:electricity --monthly

This shows month-by-month power costs. I noticed a spike in March when I was running some heavy Docker builds. That helped me realize I should schedule those at night when electricity is cheaper on my time-of-use plan.

Cost Per Device

hledger -f homelab.journal balance expenses:electricity

I can see exactly how much each device costs me per month. The Proxmox host is the biggest drain, which makes sense—it's doing most of the work.

HTML Reports

I generate monthly HTML reports and save them to the reports folder:

hledger -f homelab.journal balancesheet --output-file=/volume1/accounting/reports/balance-$(date +%Y-%m).html

These are static files I can open in a browser or share with my wife when she asks why the electric bill went up.

Automating Monthly Entries

I got tired of manually entering electricity costs every month. I wrote a small bash script that appends them automatically.

Here's monthly-electricity.sh:

#!/bin/bash

JOURNAL="/volume1/accounting/journals/homelab.journal"
DATE=$(date +%Y-%m-%d)
MONTH=$(date +%B)

cat <<EOF >> $JOURNAL

$DATE * $MONTH Electricity - Synology
    expenses:electricity:synology      \$3.53
    assets:cash

$DATE * $MONTH Electricity - Proxmox
    expenses:electricity:proxmox       \$10.08
    assets:cash

$DATE * $MONTH Electricity - Network
    expenses:electricity:network       \$2.02
    assets:cash

EOF

echo "Added electricity entries for $MONTH"

I made it executable and set up a monthly cron job on the Synology:

0 0 1 * * /volume1/accounting/scripts/monthly-electricity.sh

This runs at midnight on the first of each month. I still review the entries manually in case my power usage changed significantly.

What Worked Well

Plain-text accounting fits my workflow perfectly. I can edit journal files from my laptop, phone, or directly on the NAS. Everything lives in version control (I push the accounting folder to a private Git repo), so I have a complete history of changes.

The reports are fast. Even with hundreds of transactions, hledger processes everything in under a second. No database overhead, no web UI lag.

I like that the data format is future-proof. If hledger disappears tomorrow, I still have readable text files. I could write a Python script to parse them or import them into something else.

The electricity tracking revealed patterns I didn't expect. I thought my Synology was the power hog, but it's actually one of the most efficient devices I run. The old desktop I repurposed for Proxmox is the real culprit. That insight alone justified the time I spent setting this up.

What Didn't Work

The web interface (hledger-web) is underwhelming. It's read-only by default, and even when you enable editing, it's clunky. I tried using it for quick entries but always went back to editing the text file directly.

Manual electricity estimates are tedious. I thought about integrating with Home Assistant or a smart PDU, but that felt like overkill. I settled for updating my measurements quarterly and accepting some inaccuracy.

The learning curve for double-entry bookkeeping is real. It took me a few days to internalize why every transaction needs two entries and which accounts should increase or decrease. I made several mistakes early on where my books didn't balance, and hledger's error messages weren't always helpful.

I also struggled with how to handle depreciation. Should I track the declining value of hardware over time? I decided not to—this is expense tracking, not formal accounting. But it means my reports don't reflect the actual value of my homelab assets, only what I've spent.

Key Takeaways

If you run a homelab and want to understand your costs, plain-text accounting works. It's not the easiest option, but it's one of the most flexible.

Start simple. Don't try to track everything perfectly from day one. I began with just hardware purchases and added electricity tracking later. You can always expand your chart of accounts.

Measure what you can, estimate the rest. Perfect accuracy isn't the goal—seeing trends and making informed decisions is.

The Synology NAS is a solid platform for this. It's always on, has Docker support, and provides easy file access from other devices. I considered running hledger on Proxmox instead, but having it on the NAS means it stays available even when I'm tinkering with VMs.

Version control your journal files. I push mine to a private Git repo after every significant change. It's saved me twice when I accidentally deleted entries.

The real value isn't in the tool—it's in the habit of recording expenses consistently. Once you have a few months of data, patterns emerge. You'll see where money goes, which purchases were worth it, and what you can cut back on.

For me, the biggest surprise was realizing my homelab costs about $25/month in electricity alone. That's $300/year just to keep things running. It made me more intentional about what services I self-host versus what I pay someone else to run.