Graphden documentation

Configuration Guide

Graphden uses Integrant for component lifecycle management and Aero for configuration loading.

Configuration Files

Configuration files are located in resources/:

File Profile Purpose
system-prod.edn :prod Production deployment
system-dev.edn :dev Local development
system-test.edn :test Automated tests

System Components

The storage backend is plain PostgreSQL — graph traversal is done with recursive CTEs, not a graph-database extension. The components below start in dependency order:

:db/schema             → Schema builder (pure, no deps)
       ↓
:db/postgres           → PostgreSQL storage (jdbc-url / pool / schema)
       ↓
:app/storage           → Tenancy storage seam (identity passthrough by default)
       ↓
:db/versioned          → Versioned storage decorator (immutable history)
       ↓
:db/notify-listener    → Dedicated PG conn LISTENing on `graphden_events`
:db/service-locks      → Dedicated PG conn for advisory locks
:app/packages          → Loads resources/packages/ (core / storage / web / app-base / app / registry / mcp)
       ↓
:exec/base-fns         → Base-function registry (Clojure impls)
:exec/fn-entities      → Syncs fn-defs into storage
:vault/client          → OpenBao / Vault KV v2 client
:auth/provider         → Authentication seam (single-token by default)
       ↓
:exec/context          → Executor context
       ↓
:exec/compiled-registry   → Compile fn graphs into closures at startup
       ↓
:exec/branch-router       → Per-branch ExecutionContext + Ring dispatcher
:exec/api-url-drift-check  → Boot-time backend↔frontend URL drift guard
:exec/api-routes-js-cache  → Boot-cached `window.API` JS module
:exec/deploy-config        → Boot snapshot of the PUBLIC deployment settings
:exec/service-reconciler   → Seeds + supervises `:service` rows (runs the web server)
:exec/cleanup-scheduler    → Hourly :fn-execution TTL sweep

There is no separate :http/server component. The HTTP server is a :service row (the app package seeds a :web-server service), seeded and supervised by :exec/service-reconciler. The listen port is fixed at the Docker layer (container 8080), not via an integrant :port key.

Component Dependencies

Dependencies are expressed using Integrant references:

:db/postgres
{:schema #ig/ref :db/schema   ; Reference to :db/schema component
 :jdbc-url "..."
 ...}

Available reference types:

Aero Reader Tags

Configuration files support these reader tags:

#env - Environment Variables

Read value from environment variable:

:jdbc-url #env JDBC_URL              ; Required
:pool-size #or [#env DB_POOL_SIZE "10"]   ; With default

#or - Default Values

Provide fallback if value is nil:

:pool-size #or [#env DB_POOL_SIZE "10"]

#long - Parse as Long

Convert string to long integer:

:pool-size #long #or [#env DB_POOL_SIZE "10"]

#ig/ref - Integrant Reference

Reference another component:

:schema #ig/ref :db/schema

Package Names

Packages are loaded from resources/packages/. Configure which packages to load:

:app/packages {:package-names ["core" "storage" "web" "app-base" "app" "registry" "mcp"]}

Production loads ["core" "storage" "web" "app-base" "app" "registry" "mcp"] (registry/mcp are optional — drop either and the app still boots). Dev additionally loads "examples" (pedagogical fn-defs that must never ship to prod). The test system has no :app/packages key at all — it wires the executor directly without loading the app packages.

Component Configuration

:db/schema

Schema builder component (stateless).

:db/schema {}

:db/postgres

PostgreSQL storage backend (HikariCP pool). Graph traversal uses recursive CTEs. The executor auto-migrates its schema on startup.

Key Type Description
:jdbc-url string JDBC connection URL
:username string Database username
:password string Database password
:pool-size long HikariCP pool size
:schema ref Reference to :db/schema
:source-revision? boolean/string Install transactional source revision triggers; disabled by default
:db/postgres
{:jdbc-url #or [#env JDBC_URL "jdbc:postgresql://localhost:5432/graphden"]
 :username #or [#env DB_USERNAME "graphden"]
 :password #or [#env DB_PASSWORD "graphden"]
 :pool-size #long #or [#env DB_POOL_SIZE "10"]
 :schema #ig/ref :db/schema}

:app/storage

Tenancy storage seam. Identity passthrough by default; the tenancy addon overrides this key with an org-scoped decorator. Sits beneath versioning so the branch-router’s vs/unwrap keeps the tenant filter.

Key Type Description
:base ref Reference to :db/postgres
:app/storage
{:base #ig/ref :db/postgres}

:db/versioned

Versioned storage decorator providing immutable history.

Key Type Description
:base-storage ref Reference to :app/storage
:db/versioned
{:base-storage #ig/ref :app/storage}

:db/notify-listener

Owns a dedicated PostgreSQL connection that LISTENs on the graphden_events channel. A mutation on one pod is observed by all sibling pods within ~1s (cross-pod cache invalidation). A pool-bound connection can’t be used because the LISTEN session must stay alive forever.

:db/notify-listener
{:pg-opts
 {:jdbc-url #or [#env JDBC_URL "jdbc:postgresql://localhost:5432/graphden"]
  :username #or [#env DB_USERNAME "graphden"]
  :password #or [#env DB_PASSWORD "graphden"]}}

:db/service-locks

Owns a dedicated PostgreSQL connection for session-scoped advisory locks. The service reconciler acquires a per-service lock before starting each service; only the pod that wins runs it. Advisory locks are session-scoped, so a pool connection can’t back them.

:db/service-locks
{:pg-opts
 {:jdbc-url #or [#env JDBC_URL "jdbc:postgresql://localhost:5432/graphden"]
  :username #or [#env DB_USERNAME "graphden"]
  :password #or [#env DB_PASSWORD "graphden"]}}

:app/packages

Loads base-fns and fn-defs from resources/packages/. fn-defs are NOT a separate integrant component — they come from the packages listed here.

:app/packages
{:package-names ["core" "storage" "web" "app-base" "app" "registry" "mcp"]}

:exec/base-fns

Registers base functions from the loaded packages’ Clojure impls.

Key Type Description
:storage ref Reference to :db/versioned
:packages ref Reference to :app/packages
:exec/base-fns
{:storage #ig/ref :db/versioned
 :packages #ig/ref :app/packages}

:exec/fn-entities

Syncs the packages’ fn-def declarations into storage.

Key Type Description
:storage ref Reference to :db/versioned
:packages ref Reference to :app/packages
:base-fns ref Reference to :exec/base-fns
:exec/fn-entities
{:storage #ig/ref :db/versioned
 :packages #ig/ref :app/packages
 :base-fns #ig/ref :exec/base-fns}

:vault/client

OpenBao / Vault KV v2 client. Address + token are infrastructure-level — the user fn-graph never sees them; it calls :vault-get, which pulls the client off the executor context. When VAULT_ADDR is unset the client returns nil and :vault-get errors on use.

:vault/client
{:address #or [#env VAULT_ADDR ""]
 :token #or [#env VAULT_TOKEN ""]}

:auth/provider

Authentication seam. Default single-token provider (the token comes from AUTH_TOKEN); the tenancy addon overrides this key with session/JWT auth.

:auth/provider
{:token #or [#env AUTH_TOKEN ""]}

:exec/context

Executor context for running functions.

Key Type Description
:storage ref Reference to :db/versioned
:vault-client ref Reference to :vault/client
:pg-storage ref Raw PG storage for NOTIFY emission (:db/postgres)
:base-fns ref Ctx-scoped base-fns map (:exec/base-fns)
:auth-provider ref Reference to :auth/provider
:checker-cache? boolean/string Enable bounded pure checker artifacts for this runtime
:source-manifest? boolean/string Enable bounded client-source and manifest retention on supported revision-enabled storage
:exec/context
{:storage #ig/ref :db/versioned
 :vault-client #ig/ref :vault/client
 :pg-storage #ig/ref :db/postgres
 :base-fns #ig/ref :exec/base-fns
 :auth-provider #ig/ref :auth/provider}

Production enables checker artifacts by default. Set GRAPHDEN_CHECKER_CACHE=false and restart to disable them. Development and test configurations leave the cache off, so code reload cannot reuse proofs from an earlier checker implementation. An explicitly enabled development runtime must be halted before reloading code.

One cache is shared by all branch contexts in a runtime: 512 MiB of conservative retained/reserved charge, at most 256 MiB per checking pass, 16 entries, and a 10-minute TTL. The limit is not an eager heap allocation. Capacity or admission misses perform ordinary checking. Retiring the runtime prevents publication; in-flight reservations remain charged until their workers finish.

Only isolated checker artifacts are reused. Every request still captures fresh source, checks authorization, validates provenance and native signatures, and builds a fresh plan. Raw JDBC/source replay is not enabled by this setting.

Optional manifest retention

GRAPHDEN_SOURCE_REVISION=true enables coordinated installation of source revision triggers during PostgreSQL schema initialization. GRAPHDEN_SOURCE_MANIFEST=true enables client-source and manifest retention in the executor. Client source, manifests, server-only closures and exact witness paths use separate cache keys even for equal roots. Server retention stores raw rows only: native implementation, type/marker, callable contract and fingerprint checks still run, together with the separate fresh post-execution check. Both default to false. The second setting requires the first, a supported storage/policy adapter and an owned Hikari pool; unsupported setup fails startup.

The revision commits or rolls back with source writes. Each database backend updates one of 256 counters; readers compare their MVCC-visible sum and common generation. Independent backends usually use different counters, while bucket collisions retain normal transaction locking. This certificate does not cache authorization: hits read fresh function metadata and repeat policy, namespace and source-contract checks. Client server-call targets still require execution permission on every hit. Unrelated source writes also invalidate retained source; this setting does not accelerate every cold load.

Limits are 64 MiB retained, 64 entries, a 30-second TTL, four admitted snapshots and 32 MiB of cumulative copying per snapshot (at most 128 MiB across the four admitted snapshots). The client graph uses a columnar row representation that stores each schema’s field names once. These charges do not describe total JVM memory. Capacity or unsupported values retain ordinary collection. Ordinary closures accept at most eight roots per retained entry; exact witness paths accept up to 128 UUIDs, with their key storage included in the charge.

Source DDL and trigger repair require coordinated maintenance. Retire affected controllers before maintenance and reinitialize them afterward. The internal graphden.storage.postgres.source-revision/call-with-maintenance boundary excludes certified readers and writers and rotates the revision generation in the maintenance transaction. Disabling triggers or changing source tables outside that boundary is unsupported while manifest retention is enabled. Database writers need UPDATE permission on the revision table; installation does not elevate their privileges. Turning the flags off stops retention but does not remove installed triggers or their table.

:exec/compiled-registry

Compiles fn graphs into Clojure closures at startup. Depends on :exec/fn-entities so every composed fn is already in storage before traversal.

:exec/compiled-registry
{:context #ig/ref :exec/context
 :_fn-entities #ig/ref :exec/fn-entities}

:exec/branch-router

Per-branch ExecutionContext registry + Ring dispatcher, seeded with the default branch (main) after the compiled registry is built. The :branch-routing-wrap base-fn reads this router on each request to pick which branch’s compiled view serves the call.

:exec/branch-router
{:context #ig/ref :exec/context
 :_compiled-registry #ig/ref :exec/compiled-registry}

:exec/api-url-drift-check

Boot-time backend↔frontend URL drift guard. Walks the live router’s /api/* and /partials/* paths and scans editor JS for such literals (fetch URLs and hx-get="/partials/…" attributes built in JS strings; comment lines skipped); throws on drift so a route rename or removal that forgets the JS fails boot rather than 404ing at runtime. Routes an addon serves through the route collection carry a // api-url-drift-allow: route-collection marker on their line; routes an OPTIONAL first-party package serves (registry / mcp, per-branch) carry // api-url-drift-optional: registry-router and are checked against that router when the package is loaded, skipped when it is not. Toggle off via GRAPHDEN_SKIP_URL_DRIFT_CHECK=1.

:exec/api-url-drift-check
{:context #ig/ref :exec/context
 :_compiled-registry #ig/ref :exec/compiled-registry
 :skip? #or [#env GRAPHDEN_SKIP_URL_DRIFT_CHECK ""]}

:exec/api-routes-js-cache

Boot-time-cached window.API = {…} JS module, computed once after the router compiles. The editor addresses routes by name (API.api_branches) instead of duplicating path literals.

:exec/api-routes-js-cache
{:context #ig/ref :exec/context
 :_compiled-registry #ig/ref :exec/compiled-registry}

:exec/deploy-config

Boot-time snapshot of the public deployment settings the platform’s own UI reads at request time — resolved once from the environment (Aero #env) in the platform process and read by the pure :deploy-config base-fn (:effects #{}). Listing a variable here is the operator’s declaration that it is not secret: any graph on the instance can read it, under any effect gate. Why it exists: on the cloud every tenant request runs under the request-level effect gate, which excludes :env by design, so a partial that read the environment directly answered 500 for every tenant (TENANCY_SEAM § Effect gate). Secrets never go here — the vault or Clojure-side config (the alerter’s Telegram pair) hold those.

:exec/deploy-config
{:settings {:hub-url                 #env GRAPHDEN_HUB_URL
            :feedback-url            #env GRAPHDEN_FEEDBACK_URL
            :feedback-intake         #env GRAPHDEN_FEEDBACK_INTAKE
            :disable-asset-overrides #env GRAPHDEN_DISABLE_ASSET_OVERRIDES
            :tutorial-base           #env GRAPHDEN_TUTORIAL_BASE
            :marketplace-moderation  #env GRAPHDEN_MARKETPLACE_MODERATION
            :registry-url            #env GRAPHDEN_REGISTRY_URL}}

Blank values read as unset (nil); an undeclared key reads as nil too. :registry-url / :hub-url also scope the two deployment bearers: the remote-registry token (GRAPHDEN_REGISTRY_TOKEN) and the hub token (GRAPHDEN_HUB_TOKEN) — secrets, read from the environment, never declared here — ride only dials whose origin is the declared URL’s.

:exec/service-reconciler

Seeds the packages’ :services declarations into the :service table (idempotent, deterministic ids), then starts the enabled rows under the supervisor. This is how the HTTP server runs — the app package declares a :web-server service. Uses the notify-listener and service-locks for cross-pod coordination.

:exec/service-reconciler
{:context #ig/ref :exec/context
 :packages #ig/ref :app/packages
 :notify-listener #ig/ref :db/notify-listener
 :service-locks #ig/ref :db/service-locks
 :_compiled-registry #ig/ref :exec/compiled-registry
 :_branch-router #ig/ref :exec/branch-router}

:exec/cleanup-scheduler

Hourly sweep of :fn-execution rows past their per-status TTL. Independent of HTTP — runs even when nobody hits /api. The period is overridable via CLEANUP_PERIOD_MS.

:exec/cleanup-scheduler
{:context #ig/ref :exec/context
 :period-ms #long #or [#env CLEANUP_PERIOD_MS "3600000"]}

:exec/demo-branches (opt-in)

Seeds demo branches for the versioning UI. Only seeds when GRAPHDEN_DEMO_BRANCHES_ENABLED is truthy (1, true, yes, on). Idempotent — a branch whose :name already exists is left untouched. Real prod ships with this off; dev/docker enables it so the branch picker has content out of the box.

:exec/starter-catalogue (default on)

Publishes the marketplace’s starter catalogue — the platform’s own themes, keyboard layouts and example packages (MARKETPLACE.md § 11) — so a fresh instance’s marketplace is not empty. Runs after the packages sync, in the platform tier, through the same row a publish writes; idempotent by (name, version), so a restart adds nothing. Skipped when the optional registry package is not loaded. Set GRAPHDEN_STARTER_CATALOGUE=0 to boot without it.

:exec/starter-catalogue
{:context #ig/ref :exec/context
 :enabled? #or [#env GRAPHDEN_STARTER_CATALOGUE "1"]}

Environment Variables

The production config reads these via #env:

Variable Default Description
JDBC_URL jdbc:postgresql://localhost:5432/graphden PostgreSQL connection URL
DB_USERNAME graphden Database username
DB_PASSWORD graphden Database password
DB_POOL_SIZE 10 HikariCP pool size
VAULT_ADDR (empty) OpenBao / Vault address (unset → :vault-get errors)
VAULT_TOKEN (empty) OpenBao / Vault token
AUTH_TOKEN (empty) Single-token auth secret
GRAPHDEN_CHECKER_CACHE true Bounded checker artifacts; false disables after restart (raw source replay stays off)
GRAPHDEN_SKIP_URL_DRIFT_CHECK (empty) 1 to skip the boot URL-drift check
CLEANUP_PERIOD_MS 3600000 :fn-execution TTL sweep period (ms)
GRAPHDEN_DEMO_BRANCHES_ENABLED (empty) Truthy to seed demo branches
GRAPHDEN_STARTER_CATALOGUE 1 0 to boot without the marketplace’s starter catalogue
GRAPHDEN_SSE_PORT (unset ⇒ SSE relay off) Port for the cross-executor invalidation SSE relay (:sse/relay)
GRAPHDEN_EXECUTOR_ORGS (unset ⇒ all orgs) Org-shard predicate for this executor
GRAPHDEN_BYO_EXECUTOR (empty) Truthy marks this pod a BYO executor
GRAPHDEN_EXECUTOR_ID (empty) Fleet identity; set enables :exec/fleet-controller
GRAPHDEN_FLEET_CONTROLLER_PERIOD_MS 30000 Fleet placement-controller tick period (ms)
GRAPHDEN_MAX_CACHED_BRANCHES 16 LRU cap on warm per-branch ctx entries in the branch router (an entry idle for 15 min is dropped regardless — branch-router/*ctx-idle-ttl-ms*)

(Deployment-specific knobs read directly via System/getenv — GRAPHDEN_MAX_CONCURRENT_EXECUTIONS, GRAPHDEN_FLEET_*, the BYO vars, and the GRAPHDEN_DISABLE_ASSET_OVERRIDES rescue hatch — are covered in DEPLOYMENT.md, SCALING.md, and FLEET_DEPLOY.md.)

Accounts (opt-in identity module)

Enabled by naming the addon fragment in GRAPHDEN_ADDON_CONFIGS (comma-separated list, read in system/config.clj; each fragment deep-merges over system-<profile>.edn):

GRAPHDEN_ADDON_CONFIGS=graphden/accounts/addon.edn

The fragment (resources/graphden/accounts/addon.edn) reads via #env:

Variable Default Description
RESEND_API_KEY (empty ⇒ LogMailer) Resend API key for transactional email; unset logs the links instead
GRAPHDEN_MAIL_FROM (built-in sender) Override the From address
GRAPHDEN_APP_ORIGIN (unset ⇒ request Host) Public origin for OAuth redirect URIs + emailed links
GRAPHDEN_TUTORIAL_BASE https://graphden.dev/tutorial/ Where the interactive tour’s “Read the written lesson” links point ({id}-{slug} is appended) — a translation or an intranet copy of docs/tutorial/; a :deploy-config setting, read at boot
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET (empty ⇒ GitHub login off) GitHub OAuth app — both required to enable
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (empty ⇒ Google login off) Google OIDC client — both required to enable
TELEGRAM_BOT_TOKEN / TELEGRAM_BOT_USERNAME (empty ⇒ Telegram login off) Telegram login-widget bot — both required to enable

Each social provider is per-provider opt-in: it appears only when both of its credentials are set. See ACCOUNTS.md for the module itself (data model, /auth/* surface, editor integration).

There is no env-configurable execution max-depth, but the per-execution wall-clock deadline is tunable via GRAPHDEN_MAX_EXECUTION_WALL_MS (default 300000 = 5 min; read in crud/fn_execution/persist.clj). The dev config (system-dev.edn) reads DB settings from the GRAPHDEN_-prefixed variants (GRAPHDEN_JDBC_URL, GRAPHDEN_DB_USER, GRAPHDEN_DB_PASSWORD) and defaults to port 5434.

Profile-Specific Settings

Development (:dev)

Test (:test)

Production (:prod)

Programmatic Configuration

Starting the System

(require '[graphden.system.interface :as sys])

;; Start with profile
(def system (sys/start! :prod))

;; Start with overrides (merged per top-level key)
(def system (sys/start-with-overrides! :test
              {:db/postgres {:jdbc-url "jdbc:postgresql://localhost:5432/test"}}))

;; Start only a subset of components (and their deps)
(def system (sys/start! :prod [:db/postgres :db/versioned]))

;; Stop
(sys/stop! system)

Reading Configuration

(require '[graphden.system.interface :as sys])

(def config (sys/read-config :prod))
;; Returns raw Integrant config map

Adding Custom Components

  1. Define an init-key method in one of the graphden.system.init.* namespaces (graphden.system.core is now only a loader that :requires them for their defmethod side effects):
(defmethod ig/init-key :my/component [_ config]
  ;; Initialize and return component
  )

(defmethod ig/halt-key! :my/component [_ component]
  ;; Clean up component
  )
  1. Add to the configuration files:
:my/component
{:some-setting "value"
 :dependency #ig/ref :other/component}

Logging Configuration

Logging is configured via resources/logback.xml. See the file for pattern and level configuration.

Key MDC fields: