Install Hearth
Pick the path that fits you.
| Path | Best for | Effort |
|---|---|---|
| On EmberNet | Anyone who wants it running without owning the platform | A few clicks |
| Kubernetes with Helm | A cluster you already run | One chart, two commands |
| One box with Podman Quadlet | A single Linux server, a closet, a shop | One 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.
- Sign in to EmberCORE, or start free.
- Open the App Store, find Hearth, and choose Deploy.
- 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 need | What Hearth wants | What works |
|---|---|---|
| A place to run it | Kubernetes with Helm, or Podman with Quadlet on one box | k3s on anything, or any Linux box with Podman |
| Postgres | Postgres 17 | The one the chart runs, or your own server |
| Object storage | Any S3 API | The bundled Garage, MinIO, AWS S3, Cloudflare R2, Backblaze B2 |
| Sign-in | Optional. Any OpenID Connect provider | Vord, Authentik, Authelia, Zitadel, Google, Microsoft. Local accounts work without one |
| A secret key | 32 random bytes | openssl 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.