Install & configure / Use an existing Postgres

Use an existing Postgres

The release compose file bundles Postgres, but Jangka works with any Postgres server you already run, including managed services. It needs one database and one user.

Requirements

Requirement	Why
Postgres 18 or later	Migrations use `uuidv7()`, which Postgres 18 added. Older versions fail with `migrations failed`.
A database owned by Jangka's user	Migrations create tables, and the job queue (pg-boss) creates its own `pgboss` schema in the same database.
`pg_trgm` extension (optional)	Lets title search tolerate typos.

Create the database

Connect as a superuser or an admin role and run:

sql

CREATE USER jangka WITH PASSWORD 'choose-a-strong-password';
CREATE DATABASE jangka OWNER jangka;

-- Optional: typo-tolerant title search
\c jangka
CREATE EXTENSION IF NOT EXISTS pg_trgm;

Jangka tries to create pg_trgm itself on every start. If its user isn't allowed to, the app still runs and logs a warning (pg_trgm unavailable). Search then still works, but titles have to match without typos. Creating the extension once as an admin, as above, avoids that. Most managed Postgres services allow pg_trgm.

Point Jangka at it

Remove the postgres service and the pgdata volume from the compose file, and read DATABASE_URL from .env:

docker-compose.ymlyaml

name: jangka

services:
  app:
    image: iqbalr3000/jangka:${JANGKA_VERSION:-latest}
    container_name: jangka
    environment:
      DATABASE_URL: ${DATABASE_URL:?set DATABASE_URL}
      MASTER_KEY: ${MASTER_KEY:?set MASTER_KEY (openssl rand -base64 32)}
      PUBLIC_URL: ${PUBLIC_URL:-http://localhost:3000}
    ports:
      - "3000:3000"

.envsh

DATABASE_URL=postgres://jangka:choose-a-strong-password@db.internal:5432/jangka
MASTER_KEY=generated-with-openssl-rand-base64-32
PUBLIC_URL=https://jangka.example.com
JANGKA_VERSION=1.0.0-rc.1

The URL must start with postgres:// or postgresql://. If the password contains characters such as @, : or /, percent-encode them (@ becomes %40).

Check the connection

terminalsh

docker compose up -d
docker compose logs app

Migrations run before the app serves any traffic. If the database is unreachable or too old, the log shows migrations failed with the cause, and the container exits.