docs: add external database for k8s docs

2026-04-26 12:18:33 -05:00 · 2024-09-26 22:28:28 -04:00
parent 5f5e1e8a88
commit f0ed89d739
3 changed files with 81 additions and 88 deletions
@@ -13,6 +13,7 @@
  "kubernetes-quickstart": "Quickstart",
  "kubernetes-glasskube": "Installing with Glasskube",
  "networking": "Networking",
+  "kubernetes-external-database": "Setting up an External Database",
  "-- Managing Hatchet": {
    "type": "separator",
    "title": "Managing Hatchet"
@@ -0,0 +1,63 @@
+# Setting up Hatchet with an external database
+
+## Connecting to Postgres
+
+To connect to Postgres, the `hatchet-stack` chart requires the following configuration options:
+
+```yaml
+hatchet-api:
+  env:
+    DATABASE_URL: "postgres://<user>:<password>@<host>:5432/<db-name>?sslmode=disable"
+    DATABASE_POSTGRES_HOST: "<host>"
+    DATABASE_POSTGRES_PORT: "5432"
+    DATABASE_POSTGRES_USERNAME: "<user>"
+    DATABASE_POSTGRES_PASSWORD: "<password>"
+    DATABASE_POSTGRES_DB_NAME: "<db-name>"
+    DATABASE_POSTGRES_SSL_MODE: "disable"
+
+hatchet-engine:
+  env:
+    DATABASE_URL: "postgres://<user>:<password>@<host>:5432/<db-name>?sslmode=disable"
+    DATABASE_POSTGRES_HOST: "<host>"
+    DATABASE_POSTGRES_PORT: "5432"
+    DATABASE_POSTGRES_USERNAME: "<user>"
+    DATABASE_POSTGRES_PASSWORD: "<password>"
+    DATABASE_POSTGRES_DB_NAME: "<db-name>"
+    DATABASE_POSTGRES_SSL_MODE: "disable"
+```
+
+## Mounting environment variables
+
+Environment variables can also be mounted from secrets or configmaps via the `deploymentEnvFrom` field, which corresponds to the `envFrom` field in a Kubernetes deployment. For example, to mount the `DATABASE_URL` environment variable from a secret, you can use the following configuration:
+
+```yaml
+hatchet-api:
+  deploymentEnvFrom:
+    - secretRef:
+        name: hatchet-api-secrets
+        key: DATABASE_URL
+
+hatchet-engine:
+  deploymentEnvFrom:
+    - secretRef:
+        name: hatchet-api-secrets
+        key: DATABASE_URL
+```
+
+For more information on mounting environment variables from secrets, refer to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#configure-all-key-value-pairs-in-a-secret-as-container-environment-variables).
+
+## Migrations
+
+In order for migrations to run, the database user requires permissions to write and modify schemas **on a clean database**. It is therefore recommended to create a separate database instance where Hatchet can run and grant permissions on this database to the Hatchet user. For example, to create a new database and user `hatchet` in Postgres, run the following commands (**warning:** change the username/password for production usage):
+
+```sql
+create database hatchet;
+
+create role hatchet
+with
+    login password 'hatchet';
+
+grant hatchet to postgres;
+
+alter database hatchet owner to hatchet;
+```
@@ -10,87 +10,13 @@ import { Tabs, Steps, Callout } from "nextra/components";
 ## Quickstart

 <Steps>
-### Generate encryption keys
-
-There are 4 encryption secrets required for Hatchet to run which can be generated via the following bash script (requires `docker` and `openssl`):
-
-```sh filename=generate-keys.sh copy
-#!/bin/bash
-
-# Define an alias for generating random strings. This needs to be a function in a script.
-randstring() {
-    openssl rand -base64 69 | tr -d "\n=+/" | cut -c1-$1
-}
-
-# Create keys directory
-mkdir -p ./keys
-
-# Function to clean up the keys directory
-cleanup() {
-    rm -rf ./keys
-}
-
-# Register the cleanup function to be called on the EXIT signal
-trap cleanup EXIT
-
-# Check if Docker is installed
-if ! command -v docker &> /dev/null
-then
-    echo "Docker could not be found. Please install Docker."
-    exit 1
-fi
-
-# Generate keysets using Docker
-docker run --user $(id -u):$(id -g) -v $(pwd)/keys:/hatchet/keys ghcr.io/hatchet-dev/hatchet/hatchet-admin:latest /hatchet/hatchet-admin keyset create-local-keys --key-dir /hatchet/keys
-
-# Read keysets from files
-SERVER_ENCRYPTION_MASTER_KEYSET=$(<./keys/master.key)
-SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET=$(<./keys/private_ec256.key)
-SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET=$(<./keys/public_ec256.key)
-
-# Generate the random strings for SERVER_AUTH_COOKIE_SECRETS
-SERVER_AUTH_COOKIE_SECRET1=$(randstring 16)
-SERVER_AUTH_COOKIE_SECRET2=$(randstring 16)
-
-# Create the YAML file
-cat > hatchet-values.yaml <<EOF
-api:
-  enabled: true
-  env:
-    SERVER_AUTH_COOKIE_SECRETS: "$SERVER_AUTH_COOKIE_SECRET1 $SERVER_AUTH_COOKIE_SECRET2"
-    SERVER_ENCRYPTION_MASTER_KEYSET: "$SERVER_ENCRYPTION_MASTER_KEYSET"
-    SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET: "$SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET"
-    SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET: "$SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET"
-
-engine:
-  enabled: true
-  env:
-    SERVER_AUTH_COOKIE_SECRETS: "$SERVER_AUTH_COOKIE_SECRET1 $SERVER_AUTH_COOKIE_SECRET2"
-    SERVER_ENCRYPTION_MASTER_KEYSET: "$SERVER_ENCRYPTION_MASTER_KEYSET"
-    SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET: "$SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET"
-    SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET: "$SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET"
-EOF
-```
-
-Run this script to generate the encryption keys and the `hatchet-values.yaml` file:
-
-```sh
-bash generate-keys.sh
-```
-
-<Callout type="warning">
-  **Warning:** do not commit these keys to your Git repository, use
-  `api.envFrom` or `engine.envFrom` to pull in values from a secret.
-</Callout>
-
-### Deploy Hatchet
+### Get Hatchet Running

 To deploy `hatchet-stack`, run the following commands:

 ```sh
 helm repo add hatchet https://hatchet-dev.github.io/hatchet-charts
-helm install hatchet-stack hatchet/hatchet-stack --values hatchet-values.yaml --set api.replicaCount=0 --set engine.replicaCount=0
-helm upgrade hatchet-stack hatchet/hatchet-stack --values hatchet-values.yaml --set caddy.enabled=true
+helm install hatchet-stack hatchet/hatchet-stack --set caddy.enabled=true
 ```

 This default installation will run the Hatchet server as an internal service in the cluster and spins up a reverse proxy via `Caddy` to get local access. To view the Hatchet server, run the following command:
@@ -102,32 +28,35 @@ export CONTAINER_PORT=$(kubectl get pod --namespace $NAMESPACE $POD_NAME -o json
 kubectl --namespace $NAMESPACE port-forward $POD_NAME 8080:$CONTAINER_PORT
 ```

-And then navigate to `http://localhost:8080` to see the Hatchet frontend running.
-
-### Set up your Hatchet account
-
-You can create a new user account by clicking the `Register` button on the Hatchet login screen, and then creating a new account and tenant.
-
-Next, navigate to your settings tab in the Hatchet dashboard. You should see a section called "API Keys". Click "Create API Key", input a name for the key and copy the key. Then copy the following environment variables into a `.env` file where you'd like to run your worker:
+And then navigate to `http://localhost:8080` to see the Hatchet frontend running. You can log into Hatchet with the following credentials:

 ```
-HATCHET_CLIENT_TOKEN="<token>"
-HATCHET_CLIENT_TLS_STRATEGY=none
+Email: admin@example.com
+Password: Admin123!!
 ```

-You will need this in the following example.
-
 ### Port forward to the Hatchet engine

 ```sh
 export NAMESPACE=default # TODO: replace with your namespace
-export POD_NAME=$(kubectl get pods --namespace $NAMESPACE -l "app.kubernetes.io/name=hatchet-engine,app.kubernetes.io/instance=hatchet" -o jsonpath="{.items[0].metadata.name}")
+export POD_NAME=$(kubectl get pods --namespace $NAMESPACE -l "app.kubernetes.io/name=hatchet-engine" -o jsonpath="{.items[0].metadata.name}")
 export CONTAINER_PORT=$(kubectl get pod --namespace $NAMESPACE $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
 kubectl --namespace $NAMESPACE port-forward $POD_NAME 7070:$CONTAINER_PORT
 ```

 This will spin up the Hatchet engine service on `localhost:7070` which you can then connect to from the examples.

+### Generate an API token
+
+To generate an API token, navigate to the `Settings` tab in the Hatchet frontend and click on the `API Tokens` tab. Click the `Generate API Token` button to create a new token. Save this to a `.env` file in the root of your project.
+
+```sh
+cat <<EOF > .env
+HATCHET_CLIENT_TOKEN="<your token here>"
+HATCHET_CLIENT_TLS_STRATEGY=none
+EOF
+```
+
 ### Run your first worker

 <Tabs items={['Python', 'Typescript', 'Go']}>