Self-Hosted

Self-Hosting Homechart is easy:

• Ensure your server meets the minimum requirements
• Determine if you’ll use binaries or containers
• Install and setup PostgreSQL
• Install and setup Homechart
• If using Households, link your self-hosted instance to Homechart Cloud

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.

Install PostgreSQL

Using a Binary

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

Using a Container

Run the PostgreSQL container.

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.

Install Homechart

Using a Binary

Homechart binaries are available for various architectures and operating systems:

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)

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)

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)

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)

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)

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)

Using a Container

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

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.

Setup Homechart

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

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!

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

1. 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: {}

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