Deployment guide

Homebox

Overview

Homebox is the open-source, self-hosted home inventory and organisation system maintained by the sysadminsmedia community. Catalogue everything you own, including items with photos, receipts, purchase details and custom fields, organised into nested locations and labels. Print QR asset labels for 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. This SecureAnyCloud image runs Homebox natively as a systemd service, fronted by nginx as a TLS reverse proxy. The image ships with an empty database, so the very first person to open the site registers the owner account.

What you get:

Homebox 0.26.2 as a single Go binary at /usr/local/bin/homebox (API, web app and SQLite in one)
An nginx TLS reverse proxy on :80 (health probe and redirect) and :443 in front of Homebox, which is bound to loopback :7745
One dedicated Azure data disk, re-provisioned with every VM, that holds 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 by a one-shot service and 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 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet and subnet in the target region.

Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point, because Homebox is a lightweight single binary. For the NSG, allow inbound 22/tcp from your management network, and 80/tcp plus 443/tcp from the networks your household or team will use to reach Homebox.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Homebox by SecureAnyCloud, and select Create.

On the Basics tab, 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 select Review + create and Create.

Step 2 - Deploy from the Azure CLI

Accept the Marketplace terms once per subscription, then create the VM and open the ports:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:homebox-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name homebox \
  --image sac1647283583153:homebox-ubuntu-24-04:default:latest \
  --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

Connect over SSH as azureuser:

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

Check both services and the health endpoints:

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, which is bind-mounted onto the canonical application path. Confirm the mount:

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

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

Open a web browser and go to https://<vm-public-ip>/. The certificate generated on first boot is self-signed, so your browser shows a one-time warning. Accept it to continue. The section on enabling HTTPS with a trusted certificate 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. On a freshly deployed VM the database is empty, so the very first account created becomes the owner of a new group, which is your household inventory.

The image ships with no accounts and no default credentials at all. You can confirm this 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. Access without a token, or with a junk token, stays rejected 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 that 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 you sign in, Homebox opens the home dashboard. Quick statistics summarise your total inventory value, item count, storage locations and tags. 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 that you can rename or delete.

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. 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.

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 that 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. Check both settings:

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.

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.

These steps assume a DNS record that points 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 SecureAnyCloud support, with a guaranteed response within 24 hours and a one-hour average for critical issues. Contact sales@secureanycloud.com 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. Its 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.

Deploy on Azure

Launch Homebox on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

Homebox is the open-source, self-hosted home and asset inventory manager. Track what you own, where it is, what it cost and when it needs maintenance. Organise it by nested locations, tags and labels, with photo and document attachments, QR and asset labels, CSV import and export, and a clean web interface. It is a privacy-respecting alternative to spreadsheets and SaaS inventory tools, deployable in your own VPC.

Homebox has no built-in administrator and no default password, because the first person to register becomes the owner. Every instance of this image therefore boots to the Homebox first-run registration screen on a freshly emptied database, where you create your own administrator account.

What you get:

The Homebox server as a single Go binary that serves both the REST API and the embedded web app
nginx as a reverse proxy. The server listens on 127.0.0.1:7745 and is reached through nginx on port 80 (and 443 once you add TLS). The server and its data bind to the loopback interface only
SQLite as the datastore, a single self-contained file with no separate database server to manage
A dedicated EBS data volume mounted at /var/lib/homebox that holds the SQLite database and all uploaded attachments
No shared or default credentials in the image

Prerequisites

Before you deploy this image, you need:

An Amazon Web Services account where you can launch EC2 instances
IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
An EC2 key pair in the target Region for SSH access to the instance
A VPC and subnet in the target Region, with a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use to reach Homebox
The AWS CLI (version 2) installed locally, if you plan to deploy from the command line

Launch the instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Homebox. Select the SecureAnyCloud listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger, because Homebox is lightweight. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume and the attached data volume at their default sizes or larger.

Select Launch instance. First-boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Launch the instance from the AWS CLI

This command launches an instance from the SecureAnyCloud Homebox Marketplace AMI into an existing subnet and security group.

Replace <ami-id> with the AMI ID shown on the Marketplace listing. Replace <key-name> with your EC2 key pair name and <subnet-id> with your subnet ID. Replace <security-group-id> with a security group that opens ports 22, 80 and 443 as described in the prerequisites.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=homebox-01}]'

The command prints a JSON document on success. Note the instance ID. Once the instance is running, retrieve its public address with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Connect to the instance

Connect over SSH with the key pair you selected and the public IP address from Step 2. The SSH login user depends on the operating system of the AMI variant you launched. For Homebox 0.25 on Ubuntu 24.04, the login user is ubuntu:

ssh -i /path/to/your-key.pem ubuntu@<instance-public-ip>

The message of the day reminds you of the setup steps and the key paths. A short note that documents the registration-first setup is written to a root-only file:

sudo cat /root/homebox-credentials.txt

You can confirm that the service is healthy from the instance at any time. The status endpoint is open and returns JSON:

curl -s http://localhost/api/v1/status

Register your administrator (first run)

Open http://<instance-public-ip>/ in your browser. The database ships empty, so the first visit shows the Homebox registration screen.

Enter a name, an email address and a password, then choose Register. Homebox creates your administrator account and signs you in. This account is the owner of your inventory.

There are no shared or default credentials in this image. The administrator you create here is the only one, and the password is known only to you.

After you sign in, you land on the Homebox home dashboard. It summarises your total inventory value, item, location and tag counts, your most recently added items, and your storage locations.

Create locations, tags and items

Homebox organises your inventory by locations (where things are kept, which can be nested), tags (cross-cutting labels such as Electronics or Power Tools), and items (the things themselves, each with a value, purchase date, warranty, serial number, photos and more).

Use the Create button in the sidebar to add a location, then add items to it. Each item can carry a manufacturer, model and serial number, a purchase price and date, insurance and warranty details, and attachments. The Search view lists every item as cards or a table, filterable by location and tag.

Open any item to see its full detail: its location breadcrumb, quantity, identifiers, purchase and insurance information, maintenance log and attachments.

From the web interface, you can also import an existing inventory from CSV, generate QR or asset labels for printing, and export a bill of materials.

Use the REST API

Everything in the web app is backed by the Homebox REST API under /api/v1. Log in to obtain a bearer token, then call the API with it. The status endpoint needs no authentication:

curl -s http://localhost/api/v1/status

Requests for your data require the token returned by the login endpoint. This command confirms that an unauthenticated request to a protected endpoint is correctly rejected with HTTP 401:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost/api/v1/users/self

To obtain a token, POST your email and password to /api/v1/users/login. The JSON response contains a token field.

Pass the token as an Authorization header on subsequent requests, for example curl -H "Authorization: <token>" http://localhost/api/v1/items. The full API is documented in the Homebox project's API reference.

Disable further registration

Registration stays enabled out of the box so that you can create your first administrator. Once you have registered, you can close off further public sign-ups. Set the registration option to false in the environment file, then restart the service:

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

After this, new accounts can only be added by an existing member through the group invitation flow in the web interface.

Enable HTTPS with Let's Encrypt

Homebox is served over plain HTTP on port 80 by default, so that it works the instant the instance boots. For production use, put it behind TLS. The simplest path is certbot with the nginx plugin.

Point a DNS A record at the instance's public IP first, then run certbot for your domain. The certbot command is interactive and prompts for an email and agreement, so run it directly on the instance rather than from a script:

Install certbot and its nginx plugin: sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
Obtain and install a certificate for your domain, replacing your-domain.example.com: sudo certbot --nginx -d your-domain.example.com

Certbot edits the nginx site to add the TLS listener and an HTTP-to-HTTPS redirect, and installs a renewal timer. After it completes, Homebox is reachable over HTTPS on port 443.

Backups and maintenance

All of your data lives under /var/lib/homebox on a dedicated EBS volume. This includes the SQLite database (homebox.db) and every uploaded attachment and generated thumbnail. The simplest durable backup is a point-in-time EBS snapshot of that volume, which you can schedule with Amazon Data Lifecycle Manager.

For a file-level backup, stop the service briefly so that the SQLite database is quiesced. Then archive the data directory and start the service again:

sudo systemctl stop homebox
sudo tar -czf /tmp/homebox-backup.tgz -C /var/lib/homebox .
sudo systemctl start homebox

Copy the resulting archive to Amazon S3 or another durable store. To restore, stop the service and extract the archive back into /var/lib/homebox. Fix ownership with sudo chown -R homebox:homebox /var/lib/homebox, and then start the service.

The services are ordinary systemd units. Check their state and logs with these commands:

systemctl is-active homebox.service nginx.service journalctl -u homebox.service --no-pager | tail -n 20

Scaling and operations

Homebox is a single Go binary backed by SQLite, so it scales vertically. A t3.small comfortably serves a household or small team, and you can move to a larger instance type if you add many users and large attachments.

The database and uploads are on a dedicated EBS volume, so you can grow storage independently of the instance. Expand the volume, then run sudo resize2fs on its filesystem.

To upgrade Homebox to a newer release, replace the binary at /opt/homebox/homebox with the new version's homebox from the official release tarball, and restart the service. Always take an EBS snapshot of /var/lib/homebox first, because SQLite migrations run automatically on start and are one-way.

Support

This image is published and supported by SecureAnyCloud. Support covers deployment, upgrades, integrations, TLS termination, backups and data migration, 24/7 by email and chat.

Homebox is licensed under the GNU Affero General Public License v3.0. Homebox is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch Homebox on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS