Getting Started

Install Eden Service

For one Linux host, use the CLI quickstart: install the CLI, approve browser login, pull your licensed image and start it with persistent embedded storage. Docker Engine is sufficient; Kubernetes and external PostgreSQL/ClickHouse are not required for this single-container path.

The Helm instructions below are for customers deploying to Kubernetes. Use the chart and image from the same release. This path needs Kubernetes access, Helm 3, kubectl, curl, jq, an issued image repository/digest and an Eden license for the paid profile.

The CLI quickstart covers CLI installation, browser sign-in, the latest licensed image download, dashboard license configuration and a persistent single-container installation. The CLI works on a remote host using a short browser verification code. Keep the runtime license credential separate from the CLI's download session.

Choose the deployment

Profile	State and dependencies	Replicas
`free-tier`	Embedded Turso and DuckDB; no license key; use the free-tier chart example.	One
`single`	Embedded Turso, DuckDB, telemetry and audit outboxes on persistent storage.	One
`ha`	Customer-managed PostgreSQL and ClickHouse; private persistent state per replica; provisioned HA identities and networking.	3–7; Redis migration participant sets use 3, 5 or 7
`single-offline`	Embedded state and signed offline license inputs with a persistent anti-rollback watermark.	One in the Helm profile

Single-node state must have exactly one active process. Configure Redis or Valkey as a data endpoint; neither is an internal Eden dependency. DBOS durable workflows require PostgreSQL even with an embedded deployment. Ordinary endpoint requests and embedded migration control state do not require DBOS.

For HA, follow Deploy Eden with high availability for the Helm configuration and verification sequence, including the current HA licensing installation gate. The current single image includes online and offline licensing support. An offline deployment still needs a compatible signed lease, verifying key, bound deployment/node identities and persistent anti-rollback state; changing an environment variable does not supply these credentials. The current Helm offline profile is single-node only.

Prepare the release and secrets

Run these commands from the unpacked release source/chart directory. Supply the repository and immutable digest you received; example addresses and zero digests in the checked-in values files must be replaced.

bash

export EDEN_IMAGE_REPOSITORY='registry.example.com/eden/service-single'
export EDEN_IMAGE_DIGEST='sha256:<issued-64-hex-digit-digest>'
export EDEN_CLUSTER_UID='<stable-deployment-uuid>'
export EDEN_NODE_UUID='<node-uuid-bound-to-your-issued-license>'
export EDEN_PHONE_HOME_URL='https://license.eden.dev'
kubectl create namespace eden
umask 077
mkdir -p eden-install
cp helm/charts/eden/examples/production-single-values.yaml eden-install/values.yaml
cat >>eden-install/values.yaml <<'YAML'
fullnameOverride: eden
workload:
  deploymentStrategy:
    type: Recreate
    rollingUpdate: null
  terminationGracePeriodSeconds: 180
YAML

For an online licensed deployment, use the node UUID bound to the issued license from the license issuance metadata supplied by Eden. Ask the team for this identity if it was not included with your deployment inputs; the customer license page does not currently display it. It is different from the license UUID and the stable deployment/cluster UUID. The chart and Compose examples supply placeholder node UUIDs: replace them with this exact issued identity. Eden rejects an identity that conflicts with the credential. Do not create a random replacement node UUID during installation or an image upgrade. The source-free Docker quickstart leaves this override unset and derives the node identity from the credential automatically.

The name override makes the Service and Deployment names below eden. Recreate prevents overlapping embedded writers during replacement. The termination grace is an example budget; increase it when configured listener and exporter shutdown bounds require more time.

Use your secret manager to create a private eden-install/application.env with these three entries. Generate each value once and retain it in your recovery store. Changing the encryption key makes existing encrypted credentials unreadable; changing the JWT secret invalidates issued tokens.

text

EDEN_NEW_ORG_TOKEN=<random-bootstrap-token>
EDEN_JWT_SECRET=<base64-encoded-random-32-byte-secret>
EDEN_DB_ENCRYPTION_KEY=<random-64-character-lowercase-hexadecimal-key>

openssl rand -hex 32 and openssl rand -base64 32 generate the required formats. Store the issued license key in a separate private eden-install/license.env containing EDEN_LICENSE_KEY=. Create the referenced Secrets without putting their values in chart overrides:

bash

chmod 600 eden-install/application.env eden-install/license.env
kubectl -n eden create secret generic eden-application \
  --from-env-file=eden-install/application.env
kubectl -n eden create secret generic eden-license \
  --from-env-file=eden-install/license.env

Configure an existing image-pull Secret if your registry requires one. Edit eden-install/values.yaml for your storage class, capacity and resource limits. The example uses a 10 GiB persistent claim; size it for control state, retained telemetry, outboxes, temporary files and filesystem overhead.

Render and install

bash

helm template eden ./helm/charts/eden --namespace eden \
  -f eden-install/values.yaml \
  --set-string image.repository="$EDEN_IMAGE_REPOSITORY" \
  --set-string image.digest="$EDEN_IMAGE_DIGEST" \
  --set-string licensing.clusterUid="$EDEN_CLUSTER_UID" \
  --set-string env.EDEN_NODE_UUID="$EDEN_NODE_UUID" \
  --set-string licensing.phoneHomeUrl="$EDEN_PHONE_HOME_URL" \
  >eden-install/rendered.yaml

helm upgrade --install eden ./helm/charts/eden --namespace eden \
  -f eden-install/values.yaml \
  --set-string image.repository="$EDEN_IMAGE_REPOSITORY" \
  --set-string image.digest="$EDEN_IMAGE_DIGEST" \
  --set-string licensing.clusterUid="$EDEN_CLUSTER_UID" \
  --set-string env.EDEN_NODE_UUID="$EDEN_NODE_UUID" \
  --set-string licensing.phoneHomeUrl="$EDEN_PHONE_HOME_URL" \
  --wait --timeout 10m

Inspect the rendered image, volumes, Secret references and Services before the install. Keep the pod-facing HTTP Service private and terminate customer TLS at your ingress or load balancer. Online paid deployments validate their license before opening the listener and require continued authority connectivity.

Verify and send first traffic

bash

kubectl -n eden get pods,pvc,services
kubectl -n eden port-forward service/eden 8000:8000

Leave port forwarding running and use a second terminal:

bash

export EDEN_ORIGIN='http://127.0.0.1:8000'
curl --fail --silent --show-error "$EDEN_ORIGIN/health"
curl --fail --silent --show-error "$EDEN_ORIGIN/ready"

Both checks must succeed before proceeding. /health checks liveness; /ready also checks configured dependencies and admission. Then verify authenticated organization/node reads and a disposable endpoint write/read; readiness alone does not prove that those records are durable. Follow Quick start to create an organization, log in, connect Redis and verify a write/read round trip. Supply a backend hostname reachable from the Eden pod, rather than the workstation's localhost. Use HTTPS for access beyond this local tunnel.

Before production traffic, configure telemetry, alerts, backups, and least-privilege endpoint credentials. If startup fails, use Recovery runbooks and preserve the persistent claim and original keys while investigating.

Container deployment

For a downloaded archive, follow the source-free Docker commands in the CLI quickstart. The source/chart package also includes docker-compose.single.yaml. It mounts one named volume at /var/lib/eden. Set the same three application secrets, online license key, stable cluster UID, issued license node UUID (EDEN_NODE_UUID) and authority URL, and explicitly set EDEN_LICENSE_ENFORCEMENT=required. With a prebuilt single image:

bash

export EDEN_SINGLE_IMAGE="$EDEN_IMAGE_REPOSITORY@$EDEN_IMAGE_DIGEST"
export EDEN_LICENSE_ENFORCEMENT=required
: "${EDEN_NODE_UUID:?set the node UUID bound to the issued license}"
docker compose -f docker-compose.single.yaml up -d --no-build
docker compose -f docker-compose.single.yaml ps

The required application/license variables must be supplied from your private environment first. Compose's HTTP port publication must be protected by the host firewall or private network. docker compose down retains the named volume; down --volumes destroys it. Source builds additionally require the documented private dependency access and are separate from installing a supplied image.

Configure or replace a running image's license

For an online deployment, the runtime consumes these settings at startup:

dotenv

EDEN_LICENSE_ENFORCEMENT=required
EDEN_LICENSE_KEY=<authority-issued-license-credential>
EDEN_CLUSTER_UID=<stable-deployment-uuid>
EDEN_PHONE_HOME_URL=https://license.eden.dev
EDEN_LICENSE_VALIDATION_TTL_SECS=300
EDEN_HEARTBEAT_INTERVAL_SECS=60

Inject them through your secret manager, a private mode-0600 environment file passed to docker run --env-file, or the Helm Secret references above. Retain the same deployment identity, data volume, authentication secrets and encryption key across updates. The running image contacts the authority before opening the listener and continues license validation through heartbeats.

To replace a container's credential, update its environment/secret source and recreate it using the existing volume and deployment identity. A plain docker restart does not reload a changed environment file. For Kubernetes, update the referenced Secret and roll out the workload using its existing single-writer replacement strategy and PVC.

Verify with curl --fail "$EDEN_ORIGIN/ready" or EDEN_CLI_SERVICE_URL="$EDEN_ORIGIN" eden api request GET /ready. /health checks process liveness; /ready includes required license validation. The current runtime has no public API for replacing its credential in memory: neither customer dashboard login nor an HTTP readiness call registers a new runtime license. Offline installations instead require the matching offline image, signed lease and trust files, and durable anti-rollback state; an online environment credential cannot substitute for an offline lease.