Skip to content

Self hosting

Jump to bottom
xNifty edited this page Oct 11, 2026 · 3 revisions

Requirements

  • Go 1.24+ (only if you build from source; Release binaries need no Go)
  • PostgreSQL. The pg_trgm extension is used for fast search when available. Ordryn creates it if the database user is allowed to, and falls back to slower search otherwise.
  • Redis (required for API auth, rate limits, device SSO, undo, and live updates)
  • Node.js + npm (to build or develop the Vue UI, or use the web-dist zip from a release)

Quick start (full mode)

Default path: one process serves /api/v2 and the Vue UI at / (or under BASE_PATH, for example /gotodo/).

  1. Copy the example env file and edit values:
cp .env.example .env

.env is required. The process exits on startup if the file is missing from the working directory, or if any required variable is empty or invalid.

Required values:

DB_HOST=localhost
DB_PORT=5432
DB_USER=youruser
DB_PASSWORD=yourpassword
DB_NAME=ordryn
SESSION_KEY=your-32-char-or-longer-secret-key!!
REDIS_URL=redis://localhost:6379/0

Optional keys and bootstrap flags are listed in Configuration and .env.example.

The server listens on 127.0.0.1:8080 by default. That is right behind a reverse proxy on the same host. To open it to other machines directly, set HOST=0.0.0.0.

  1. Build the Vue UI (without web/dist, the UI path returns 503):
npm run build:web
  1. Run the server (make run stamps the latest git tag into the process):
make run

Or go run . from a tagged checkout (version is resolved from git describe at start). For a binary you will copy out of the tree (systemd, /var/www/…), stamp the tag at compile time; see Building-the-server:

make build
./GoTodo

Open http://localhost:8080/

After first login

As the admin, open Admin and review:

  • Site settings: registration, invites, trash retention, attachments, REST API.
  • Email: a Mailgun or SMTP provider, needed for password resets.
  • Image hosting: local disk or S3 for pasted images and avatars.
  • Extensions: enable any you've installed.

Details: Admin-settings.

API-only mode

Run the JSON API without serving the UI:

export ORDRYN_MODE=api
export ORDRYN_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
export ORDRYN_BOOTSTRAP_ADMIN_PASSWORD='choose-a-strong-password'
export ORDRYN_BOOTSTRAP_ENABLE_API=true
export ORDRYN_BOOTSTRAP_CREATE_API_KEY=true
# Also set DB_*, SESSION_KEY, REDIS_URL in .env

go run . --mode=api
curl -s http://localhost:8080/api/v2/health

On first boot, bootstrap may print a one-time API key named bootstrap. Use Authorization: Bearer <key> against /api/v2. See API.

In api mode, / is not the web app (expect 404).

Data on disk

Everything important is in PostgreSQL, including task attachments. Back up the database. Also back up these directories, relative to the working directory, if you use them:

Path Contents
.env Required config, including SESSION_KEY, which decrypts stored secrets
data/uploads/ Images, when image hosting is set to Local
data/extensions/ Installed extensions (EXTENSIONS_DIR)
config/config.json Optional site overlay

Database

Migrations run automatically on startup (internal/storage/migrations.go). You do not run a separate migrate command.

Next

Getting started

Using the API

Help

Clone this wiki locally