Homebox on Ubuntu 24.04 on Azure User Guide

Overview

Homebox is the open source, self hosted home inventory and organisation system maintained by the sysadminsmedia community. Catalogue everything you own: items with photos, receipts, purchase details and custom fields, organised into nested locations and labels. Print QR asset labels to stick on bins and shelves, log maintenance and repairs, track warranty expiry, and import or export your whole inventory as CSV. Multi user groups let a household share one inventory with invitation links.

Homebox is written in Go as a single binary with the web app and an embedded SQLite database compiled in, so it is tiny, fast and simple to operate. The cloudimg image runs Homebox natively as a systemd service bound to the loopback interface on port 7745, fronted by nginx as a TLS reverse proxy on ports 80 and 443. On the first boot of every VM a one shot service generates a per VM self signed certificate, and the image ships with an empty database so the very first person to open the site registers the owner account. Backed by 24/7 cloudimg support.

What is included:

• Homebox 0.26.2 single Go binary at /usr/local/bin/homebox (API plus web app plus SQLite in one)
• nginx TLS reverse proxy on :80 (health probe plus redirect) and :443 in front of Homebox (bound to loopback :7745)
• One dedicated Azure data disk, re-provisioned with every VM, holding the SQLite database and all uploaded photos and attachments at /var/lib/homebox
• A per VM self signed TLS certificate and API key pepper generated on first boot, never baked into the image
• Zero accounts at capture: the first visitor registers the owner, and no shared credential ships
• homebox.service and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point; Homebox is a lightweight single binary. NSG inbound: allow 22/tcp from your management network, and 80/tcp plus 443/tcp from the networks your household or team will reach Homebox on.

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Homebox by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), HTTP (80) and HTTPS (443). Review the dedicated data disk on the Disks tab, then Review + create and Create.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name homebox \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name homebox --port 80 --priority 1010
az vm open-port --resource-group <your-rg> --name homebox --port 443 --priority 1020

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

First boot initialisation completes in well under a minute; the per VM certificate is in place and the empty database is ready by the time SSH is available.

Step 4 — Confirm the services are running

systemctl is-active homebox.service nginx.service
curl -fsS http://127.0.0.1/healthz; echo
curl -fsS http://127.0.0.1:7745/api/v1/status; echo

Both services report active, the nginx health probe on port 80 returns ok, and the Homebox status endpoint returns JSON with "health":true and the version. The SQLite database and every uploaded photo live on a dedicated Azure data disk, bind mounted onto the canonical application path:

findmnt -no SOURCE,SIZE,FSTYPE,TARGET /var/lib/homebox

Both services active, the nginx and application health endpoints, and the dedicated Azure data disk holding your inventory.

Step 5 — Register the first account (this becomes your group owner)

Open a web browser and navigate to https://<vm-public-ip>/. Because the certificate generated on first boot is self signed, your browser shows a one time warning the first time; accept it to continue (Step 10 replaces it with a real certificate). Homebox shows its sign in page with a Register link. Select Register and enter your name, email and a password. The very first account created on a fresh VM becomes the owner of a new group, which is your household inventory.

The Homebox registration form. On a freshly deployed VM the database is empty, so the first person to register becomes the group owner.

The image ships with no accounts and no default credentials at all. You can confirm the no default login posture from the VM: the database contains zero users until you register, and unauthenticated API requests are rejected.

curl -sk -o /dev/null -w 'no token   -> HTTP %{http_code}\n' https://127.0.0.1/api/v1/users/self
curl -sk -o /dev/null -w 'junk token -> HTTP %{http_code}\n' -H 'Authorization: Bearer invalid' https://127.0.0.1/api/v1/users/self

Both unauthenticated calls return HTTP 401.

The shipped image carries zero accounts, and unauthenticated or junk token access is rejected with HTTP 401 until you register your own owner account.

Step 6 — Lock down registration (recommended)

Once you and your household members have registered, disable further sign ups so nobody else can create an account on your instance:

sudo sed -i 's/^HBOX_OPTIONS_ALLOW_REGISTRATION=.*/HBOX_OPTIONS_ALLOW_REGISTRATION=false/' /etc/homebox/homebox.env
sudo systemctl restart homebox

You can invite additional household members at any time from the group settings using an invitation link, even with public registration turned off.

Step 7 — Explore your dashboard

After signing in, Homebox opens the home dashboard. Quick statistics summarise your total inventory value, item count, storage locations and tags, and a Recently Added table lists your latest items with quantity, insured status and purchase price. New instances start with a set of common storage locations you can rename or delete.

The Homebox dashboard: total value, item and location counts, and a recently added table.

Step 8 — Create locations and add items

Select Locations to build a tree that mirrors your home (house, garage, loft, and rooms nested inside them). Then use the green Create button to add items to a location. Every item can carry a photo, a description, quantity, purchase price, purchase source and date, warranty expiry, serial and model numbers, the manufacturer, whether it is insured, custom fields and labels. Browse everything from the Items view as cards or a table, filtered by location or tag.

The items view. Each card shows the item, its storage location and quantity.

Open any item to see its full detail page, including the fields you recorded and the maintenance log. From here you can print a QR asset label to stick on the physical item or shelf, create sub items, and add attachments such as receipts and manuals.

An item detail page showing serial and model numbers, manufacturer, and insured status.

Step 9 — Print QR labels, log maintenance and invite your household

• QR asset labels — open an item and use the label maker to generate a printable QR code; stick it on the item or its bin, and scan it later to jump straight to that item.
• Maintenance and warranties — record maintenance entries against an item on its Maintenance tab, and set warranty expiry dates so you can find everything still under warranty.
• Household members — open the group settings and create an invitation link to share one inventory with the rest of your household; each member signs in with their own account.
• Import and export — Homebox can import and export your whole inventory as CSV from the tools section, which is handy for bulk edits, moving house, or insurance records.

Security baseline

The image ships fully patched at capture time and keeps patching itself: Ubuntu's unattended-upgrades service is enabled, so security updates are installed automatically on your running VM. The Homebox application binds to the loopback interface only, so nginx is the single network facing entry point.

systemctl is-enabled unattended-upgrades
grep -h . /etc/apt/apt.conf.d/20auto-upgrades
sudo ss -tlnH 'sport = :7745'

The :7745 application port is bound to 127.0.0.1 only; nginx on :80 and :443 is the sole way in from the network.

Automatic security updates enabled, and the Homebox application bound to the loopback interface only.

Enabling HTTPS with a trusted certificate

The image serves HTTPS on port 443 with a per VM self signed certificate out of the box, so logins are encrypted immediately. For any deployment reachable by real users, replace it with a trusted certificate. The image ships with nginx, which certbot can configure automatically. The following assumes a DNS record pointing your fully qualified domain name at the VM's public IP address, with 443/tcp open in the NSG:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d inventory.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

certbot installs the trusted certificate into the existing nginx site and sets up automatic renewal. If your inventory is private, also restrict 443/tcp in the NSG to the specific networks that should reach it.

Backup and maintenance

Homebox keeps everything, the SQLite database plus every uploaded photo and attachment, under a single directory on the dedicated data disk: /var/lib/homebox. Backing up that one directory captures your entire inventory. Stop the service briefly for a consistent copy:

sudo systemctl stop homebox
sudo tar czf <backup-dir>/homebox-$(date +%F).tgz -C /var/lib homebox
sudo systemctl start homebox

Because the database and photos live on their own Azure data disk, you can also take a coordinated Azure disk snapshot. Keep the OS patched with sudo apt update && sudo apt upgrade. To upgrade Homebox, replace /usr/local/bin/homebox with a newer release binary and restart the service; database migrations run automatically on start. See https://homebox.software/.

Support

This image is backed by 24/7 cloudimg support. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk for help with deployment, upgrades, TLS termination, backups and data disk management.

For general Homebox questions consult the documentation at https://homebox.software/. Homebox is licensed under AGPL 3.0 and is a project of the sysadminsmedia community; use here is nominative and does not imply affiliation or endorsement. All product and company names are trademarks or registered trademarks of their respective holders.