Skip to content
Engram Docs

Quickstart

Prereqs: Docker Engine 24+, ~4 GB RAM free, a domain pointing at the host (for TLS), and a few minutes.

1. Pull the Compose stack

Section titled “1. Pull the Compose stack”
Terminal window
git clone https://github.com/engram-app/engram
cd engram
# .env.example coming with the public release; for now compose
# the env file yourself from the variables in section 2

2. Set required env vars

Section titled “2. Set required env vars”

Open .env and set at minimum:

Terminal window
# Web URL where users will reach Engram
ENGRAM_PUBLIC_URL=https://engram.example.com


# Cookie/session secret — generate with `openssl rand -base64 48`
SECRET_KEY_BASE=...


# Encryption master key — generate with `openssl rand -base64 32`
# CRITICAL: this key encrypts all per-user DEKs. Losing it = data loss.
ENCRYPTION_MASTER_KEY=...


# Embedding provider (set to ollama for self-host; default is voyage)
EMBED_BACKEND=ollama
EMBED_MODEL=nomic-embed-text


# Storage backend
STORAGE_BACKEND=s3
STORAGE_ENDPOINT=http://minio:9000
STORAGE_ACCESS_KEY_ID=...
STORAGE_SECRET_ACCESS_KEY=...
STORAGE_BUCKET=engram-attachments

See Environment Variables for the full list and defaults.

3. Bring it up

Section titled “3. Bring it up”
Terminal window
docker compose up -d

First boot pulls Ollama models — that can take a few minutes depending on bandwidth. Subsequent boots are instant.

Watch logs:

Terminal window
docker compose logs -f engram

You’ll see migrations apply, then Engram listening on port 4000.

4. Reverse proxy + TLS

Section titled “4. Reverse proxy + TLS”

Engram doesn’t terminate TLS. Use Caddy (one-line config), Nginx, nginx-proxy-manager, or whatever fronting proxy you already run.

Caddy example (/etc/caddy/Caddyfile):

engram.example.com {
  reverse_proxy localhost:4000
}

Reload Caddy. TLS provisions automatically from Let’s Encrypt.

5. Create your first user

Section titled “5. Create your first user”

When PADDLE_API_KEY is unset (self-host mode), Engram’s onboarding wizard short-circuits and signup works in-app:

  1. Visit https://engram.example.com in a browser
  2. Use the Sign up form — POST /api/auth/register (email + password) creates the user via the local auth provider
  3. Log in; the vault opens directly without the billing/onboarding gate

If you’d rather create users out-of-band, an IEx shell also works:

Terminal window
docker compose exec engram bin/engram remote
{:ok, user} = Engram.Accounts.create_user(%{
  email: "you@example.com",
  password: "a strong passphrase"
})

6. Point Obsidian at your instance

Section titled “6. Point Obsidian at your instance”

In Obsidian: Settings → Engram Vault Sync → Server URL → https://engram.example.com. Sign in. Push your vault. Done.

Next steps

Section titled “Next steps”