Quickstart#

Get a local opendray-v2 instance running in about five minutes.

Prerequisites#

Verify:

5-minute path#

You should now have:

Stop the server with Ctrl-C. Stop the Postgres with `systemctl stop postgresql # or brew services stop postgresql

Frontend hot-reload (optional)#

For iterating on the React SPA without rebuilding the Go binary:

Vite proxies /api calls (REST + WebSocket) to :8770, so the dev experience is identical to production.

Using your own Postgres#

If you already have a Postgres 15+ instance, skip step 1 and edit config.toml instead:

Required: pgvector extension#

Opendray's memory subsystem needs the pgvector extension. A locally-installed Postgres uses the pgvector/pgvector:pg17 image which preinstalls and auto-enables it, so no manual step there. For a BYO Postgres, install pgvector once with a superuser before running opendray migrate:

After that, opendray's regular CRUD-only role can run migrations without needing further superuser access — migration 0011_memory just creates the memories table (the extension is already present).

Recommendations#

• Create a project-scoped role with only the CRUD privileges opendray needs — never use postgres / superuser at runtime.
• Rotate credentials out of band; don't commit them.
• Connection pool size is configurable via [database].max_conns (default 16).
• Supported Postgres versions: 15, 16, 17. The encrypted-backup subsystem additionally requires pg_dump / pg_restore matching the server's major version (see operator-guide.md [backup]).

Running the test suite#

Optional: encrypted DB backups + data exports#

Restart opendray serve; a Backups page appears in the admin sidebar (/backups) along with /export for zip-bundle data exports and imports. See docs/operator-guide.md §Backup for the full lifecycle.

Building a single distributable binary#

The repo ships a goreleaser config for cross-platform release builds:

For tagged releases, goreleaser release produces a draft GitHub release; a maintainer reviews the notes and publishes.

Troubleshooting#

pnpm build fails / internal/web/dist is empty#

The Go binary uses //go:embed all:dist and refuses to start with an empty dist/. Run cd app/web && pnpm build and confirm the directory is populated. If you only need the API and want to skip the web build, run the Vite dev server (pnpm dev) instead.

go run ./cmd/opendray migrate reports connection refused#

Postgres is not running, or the DSN in config.toml is wrong. Check `systemctl is-active postgresql # should print active

go test ./internal/memory/summarizer/... says --- SKIP#

Expected behaviour. Those tests need a real Postgres; export OPENDRAY_DEV_DB_URL (see Running the test suite above) and re-run.

Port 5432 / 8770 already in use#

Kill the conflicting process or change the port:

• Postgres: edit your PG config (port in postgresql.conf) and update config.toml accordingly.
• Gateway: edit listen = "127.0.0.1:8770" in config.toml (or set OPENDRAY_LISTEN).

Next steps#

• README.md — high-level project overview
• CONTRIBUTING.md — how to send a PR
• SECURITY.md — vulnerability disclosure