Self-Hosted

Guides for Self-Hosting Homechart

1. Requirements

The server component of Homechart is written in Go and has very low resource requirements:

1 CPU
512MB RAM

2. Containers vs Binaries

Homechart can be self-hosted using containers or binaries (or a mix of both):

Binaries use a Linux service manager like systemd.
Containers require a runtime like Docker, Podman, or Kubernetes. You should understand how these work prior to choosing this method.

3. Install and Setup PostgreSQL

Homechart requires full access to a PostgreSQL 16 database. Older or newer versions may work, but they are not tested. Homechart can share an existing PostgreSQL server, just create a new database for it.

3.1. Install PostgreSQL

3.1.1. Using a Binary

Install PostgreSQL using your distribution’s package manager or from source. Instructions can be found on PostgreSQL’s website.

3.1.2. Using a Container

Run the PostgreSQL container.

3.2. Setup PostgreSQL

Create a database for Homechart on a PostgreSQL server with these commands, replacing the database name, username and password if necessary:

CREATE DATABASE homechart;
CREATE ROLE "homechart" WITH CREATEDB LOGIN PASSWORD 'homechart';
REVOKE ALL PRIVILEGES ON SCHEMA public FROM public;
GRANT ALL PRIVILEGES ON DATABASE homechart TO "homechart";
GRANT ALL PRIVILEGES ON SCHEMA public TO "homechart";

4. Install and Setup Homechart

Homechart is distributed as a single Go binary or a container. Both are effectively the same app, just packaged differently.

4.1. Install Homechart

4.1.1. Using a Binary

Homechart binaries are available for various architectures and operating systems:

OS	Arch	Assets	Install
darwin	amd64	homechart_darwin_amd64.bom.json homechart_darwin_amd64.gz homechart_darwin_amd64.sha256	curl -L https://homechart.app/releases/homechart_darwin_amd64.gz -O \| gzip -d > homechart chmod +x homechart sha256sum homechart \| grep $(curl -L https://homechart.app/releases/homechart_darwin_amd64.sha256)
darwin	arm64	homechart_darwin_arm64.bom.json homechart_darwin_arm64.gz homechart_darwin_arm64.sha256	curl -L https://homechart.app/releases/homechart_darwin_arm64.gz -O \| gzip -d > homechart chmod +x homechart sha256sum homechart \| grep $(curl -L https://homechart.app/releases/homechart_darwin_arm64.sha256)
linux	amd64	homechart_linux_amd64.bom.json homechart_linux_amd64.gz homechart_linux_amd64.sha256	curl -L https://homechart.app/releases/homechart_linux_amd64.gz -O \| gzip -d > homechart chmod +x homechart sha256sum homechart \| grep $(curl -L https://homechart.app/releases/homechart_linux_amd64.sha256)
linux	arm	homechart_linux_arm.bom.json homechart_linux_arm.gz homechart_linux_arm.sha256	curl -L https://homechart.app/releases/homechart_linux_arm.gz -O \| gzip -d > homechart chmod +x homechart sha256sum homechart \| grep $(curl -L https://homechart.app/releases/homechart_linux_arm.sha256)
linux	arm64	homechart_linux_arm64.bom.json homechart_linux_arm64.gz homechart_linux_arm64.sha256	curl -L https://homechart.app/releases/homechart_linux_arm64.gz -O \| gzip -d > homechart chmod +x homechart sha256sum homechart \| grep $(curl -L https://homechart.app/releases/homechart_linux_arm64.sha256)
windows	amd64	homechart_windows_amd64.bom.json homechart_windows_amd64.gz homechart_windows_amd64.sha256	curl -L https://homechart.app/releases/homechart_windows_amd64.gz -O \| gzip -d > homechart chmod +x homechart sha256sum homechart \| grep $(curl -L https://homechart.app/releases/homechart_windows_amd64.sha256)

Updating Homechart

Homechart can be updated by replacing the binary with the latest version.

4.1.2. Using a Container

Homechart containers are available on GitHub. See the platform specific Installation Guides for usage.

4.1.3. SBOM

Homechart ships with a Software Bill of Materials (SBOM) manifest generated using CycloneDX. The .bom.json manifest is available with the other Binary Assets.

4.2.2 Setup Homechart

Homechart can be configured using a configuration file, environment variables, command line arguments, or using the web interface. See the Config Reference for details.

HTTPS

Homechart should be accessed over HTTPS. Certain functionality will only work this way. By default, Homechart is only available using HTTP, you’ll need to add a certificate to Homechart or your reverse proxy.

5. (Optional) Link Households to Homechart Cloud

Using households in Homechart requires a subscription, even for self-hosted users. You can subscribe monthly or purchase a lifetime subscription.

You’ll need to link your self-hosted household to a household on Homechart Cloud to use your subscription. No data is transferred to Homechart Cloud, it’s just used to transfer the subscription details.

Your self-hosted instance can create an account and household on Homechart Cloud for you automatically by tapping “Create New Household with my Email Address” under the Subscription menu option.

Otherwise, follow these steps to sign up and link an account:

Sign up for a new account on Homechart Cloud
On Homechart Cloud, create a household and setup a subscription (either during setup or under https://web.homechart.app/subscription)
On your self-hosted instance, go to Subscription in the menu and copy the Self-Hosted ID
On Homechart Cloud, paste the Self-Hosted ID into the appropriate field. Your household should now be linked!

6. Update Homechart

Homechart is meant to be easily upgradable regardless of the installation method.

6.1. Using a Binary

Download a new copy of homechart_latest to install or update Homechart. You can compare the SHA-512 sum of your existing executable to see if you need to update. See Binary Install, it’s the same process as installing.

6.2. Using a Container

Pull the latest container to update Homechart, e.g.:

docker pull ghcr.io/candiddev/homechart:latest

Depending on how you’re running Homechart, you may need to remove the existing Homechart container, pod, or re-run docker-compose up

7. Backup Homechart

Please remember to backup your data! Self-hosted Homechart is easy to backup: all persistent data is stored in PostgreSQL, Homechart doesn’t save anything locally. You can use tools like pg_dump or wal-g to perform the backup.

Additionally, you can have your self-hosted instance perform automated, encrypted backups to Homechart Cloud. Visit /subscription on your self-hosted instance to enable this.

Installation Guides

Docker

docker run -e homechart_postgresql_hostname=homechart -e homechart_postgresql_password=homechart -e homechart_postgresql_username=homechart -p 3000:3000 -d ghcr.io/candiddev/homechart:latest

Docker Compose

Create this docker-compose.yml file:

version: "3"
services:
  homechart:
    depends_on:
      - postgres
    environment:
      homechart_database_uri: postgresql://postgres:postgres@postgres/postgres
    image: ghcr.io/candiddev/homechart:latest
    ports:
      - "3000:3000"
    restart: always
  postgres:
    environment:
      POSTGRES_PASSWORD: postgres
    image: docker.io/postgres:16
    restart: always
    volumes:
      - postgres:/var/lib/postgresql/data
volumes:
  postgres: {}

Run docker-compose up -d

Kubernetes (via Helm)

helm repo add homechart https://helm.homechart.app/
helm install my-homechart homechart/homechart

Podman

podman run -e homechart_database_uri=postgresql://homechart:homechart@postgresql/homechart -p 3000:3000 -d ghcr.io/candiddev/homechart:latest