Skip to main content

Install Hearth

Pick the path that fits you.

PathBest forEffort
On EmberNetAnyone who wants it running without owning the platformA few clicks
Kubernetes with HelmA cluster you already runOne chart, two commands
One box with Podman QuadletA single Linux server, a closet, a shopOne script

Hearth does not support Docker, and there is no Compose file. Container builds use a Containerfile.

On EmberNet​

EmberNet runs the platform underneath Hearth, so there is nothing to install.

  1. Sign in to EmberCORE, or start free.
  2. Open the App Store, find Hearth, and choose Deploy.
  3. Open Hearth from your running apps and create the owner account.

Then take your first steps.

Kubernetes with Helm​

You need a Kubernetes cluster with an ingress controller, and Helm 3. The chart can run Postgres and object storage for you, so a fresh cluster is enough.

1. Add the chart repository.

helm repo add hearth https://embernet-ai.github.io/hearth/
helm repo update

2. Create the secret. The chart never makes its own credentials, because credentials that change on every upgrade log everyone out.

kubectl create namespace hearth
kubectl -n hearth create secret generic hearth \
--from-literal=POSTGRES_PASSWORD="$(openssl rand -hex 24)" \
--from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32)"

Keep the encryption key in your password manager. It seals the few values Hearth has to read back, such as a person's Google connection. If you lose it, those people connect again, and nothing else is lost.

3. Write a values file.

# my-values.yaml
ingress:
className: nginx # your ingress controller; the chart default is traefik
host: hearth.example.com
tls:
certManager:
enabled: true
issuerName: letsencrypt-prod
hearth:
publicBaseUrl: https://hearth.example.com
s3:
publicEndpoint: files.example.com # a name that differs from the internal storage address

4. Install.

helm install hearth hearth/hearth -n hearth -f my-values.yaml

5. Open the address and create the owner account. The first visitor claims the installation, so do this before you share the link.

The chart runs one Hearth pod, a Postgres 17 StatefulSet, and Garage for object storage, and a nightly backup job. To use a different ingress certificate setup, the chart supports cert-manager, a Traefik certificate resolver, or neither, which leaves TLS to whatever sits in front.

One box with Podman Quadlet​

This runs Hearth, Postgres 17, and Garage as rootless systemd services on one Linux machine, and keeps them updated from their registries. It needs Podman 4.9 or newer, systemd, openssl, and curl. It has been run on Ubuntu 24.04 with Podman 4.9.3.

git clone https://github.com/Embernet-ai/hearth
cd hearth/deploy/quadlet
./install.sh https://hearth.example.com

The script creates the secrets as Podman secrets, writes the Garage configuration, installs the Quadlet units under ~/.config/containers/systemd/, sets up object storage, and starts everything. Hearth listens on 127.0.0.1:8080. Put a reverse proxy with TLS in front of it, then open your address and create the owner account.

Settings live in ~/.config/hearth/hearth.env. After editing it, run systemctl --user restart hearth. The services start at boot and keep running after you log out. A daily timer pulls new images and restarts what changed.

Hard mode: host it your way​

Hearth is one Go program. What it needs around it:

You needWhat Hearth wantsWhat works
A place to run itKubernetes with Helm, or Podman with Quadlet on one boxk3s on anything, or any Linux box with Podman
PostgresPostgres 17The one the chart runs, or your own server
Object storageAny S3 APIThe bundled Garage, MinIO, AWS S3, Cloudflare R2, Backblaze B2
Sign-inOptional. Any OpenID Connect providerVord, Authentik, Authelia, Zitadel, Google, Microsoft. Local accounts work without one
A secret key32 random bytesopenssl rand -base64 32

Optional extras: OpenSearch for typo-tolerant search (Postgres full text search works without it), an SMTP relay so Hearth can send email, inbound mail delivery into a space, and a Google connection for each person.

Your own Postgres​

Turn off the bundled database and say where yours is.

postgresql:
enabled: false
externalDatabase:
host: db.example.com
port: 5432
user: hearth
database: hearth
sslmode: verify-full # disable, allow, prefer, require, verify-ca, or verify-full

The password comes from the POSTGRES_PASSWORD key of the hearth secret. If the password has characters a URL does not like, put a whole connection string in the secret instead and name its key:

externalDatabase:
dsnKey: DATABASE_DSN # a key in the hearth secret holding postgres://user:pass@host:5432/hearth?sslmode=require

On Podman, set HEARTH_DATABASE_URL in the hearth-database-url secret.

Your own object storage​

Turn off Garage and point at any S3 API.

garage:
enabled: false
s3:
endpoint: s3.eu-central-1.amazonaws.com # host and port, no scheme
region: eu-central-1
useSSL: true
pathStyle: false # true for most self-hosted stores
bucket: hearth
publicEndpoint: files.example.com

The access key and secret key go in the hearth secret as S3_ACCESS_KEY and S3_SECRET_KEY. Create the bucket first, or let Hearth create it if the key is allowed to. On Podman, the matching settings are HEARTH_S3_ENDPOINT, HEARTH_S3_REGION, HEARTH_S3_USE_SSL, and HEARTH_S3_PATH_STYLE.

Sign-in with your own provider​

Register a client with your provider using this redirect address, then add its secret to the hearth secret as OIDC_CLIENT_SECRET:

https://hearth.example.com/auth/callback

Vord:

oidc:
enabled: true
issuer: https://vord.example.com/id/realms/example # no trailing slash
clientId: hearth
allowedDomains: example.com
requiredRoles: hearth-users # optional: a realm role, client role, or group

Google:

oidc:
enabled: true
issuer: https://accounts.google.com
clientId: 1234567890-abc.apps.googleusercontent.com
allowedDomains: example.com

allowedDomains limits sign-in to your company's email domains. Without it, any identity the provider vouches for is accepted. Local accounts keep working next to single sign-on.

Search, mail, and backups​

opensearch:
enabled: true # adds a JVM that wants about 1 to 2 GB
mail:
smtp:
host: smtp.example.com:587
from: hearth@example.com
username: hearth # password goes in the hearth secret as SMTP_PASSWORD

The chart's backup job runs nightly at 02:30 and keeps fourteen archives. hearthctl backup takes one, hearthctl verify checks it, and hearthctl can restore it onto a spare database so you can time a recovery before you need one.

How big​

For a small team, start with 2 CPUs and a few gigabytes of memory. The chart's defaults are modest: Hearth asks for 64 MiB and is limited to 256 MiB, Postgres is limited to 1 GiB, and OpenSearch, if you turn it on, wants 1 to 2 GiB. Give Postgres a fast disk. File storage grows with what people attach.