Skip to content
Xentium Docs

Installing from source

Prerequisites

Section titled “Prerequisites”
  • Node.js 24 (there’s an .nvmrc, so nvm use works)
  • pnpm 10 (corepack enable gets you the version pinned in package.json)
  • Docker with Compose for PostgreSQL and Redis, or your own Postgres 17 and Redis 7

You don’t write any config files. The install wizard asks for your database details, generates the secrets and writes .env for you.

Quick start

Section titled “Quick start”
Terminal window
# 1. Clone and install
git clone https://github.com/slaxxer/xentium.git
cd xentium
corepack enable          # gets the pinned pnpm version
pnpm install


# 2. Start everything: Postgres + Redis containers, Prisma client, api + worker + web
./xentium.sh

Open http://localhost:5173 and you’ll land in the install wizard. It does the rest in the browser: checks your database, generates the secrets, writes .env, applies the schema and creates your admin account. You don’t restart anything.

If you use our Docker setup, enter this in the wizard’s database step: host localhost, port 5432, database xentium, user xentium, password xentium.

Already have a .env (an existing install, CI, a restored config)? The wizard notices, and the database step only tests the connection. It doesn’t overwrite anything.

./xentium.sh starts the containers, waits until they’re healthy, then runs the API, the BullMQ worker and the web app together. Ctrl+C stops the apps but leaves the containers running so the next start is quick. ./xentium.sh down stops those too.

Default ports: API 4000, web 5173, Postgres 5432, Redis 6379.

First run

Section titled “First run”

Until the site is installed, an install guard blocks every route except the installer, and the web app sends you to /install. The wizard goes through these steps:

  1. Welcome
  2. Environment check. On a fresh clone it checks the Node version, whether .env is writable and the data directory. With an existing .env it checks Node, PostgreSQL, Redis, disk and config.
  3. Database. On a fresh clone you enter your PostgreSQL details (host, port, database, user, password, and a Redis URL under Advanced if you need one). We test the connection, generate COOKIE_SECRET, JWT_SECRET, REFRESH_TOKEN_HMAC_SECRET and DUMMY_ARGON2_HASH, write .env and switch to the full app. With an existing .env this step is just a connection test.
  4. Site config: name, URL, default language, timezone.
  5. Admin account: your first administrator.
  6. Finalize: prisma migrate deploy applies the schema, we seed the core groups, permissions and system profile fields, and write a site.id to settings.
  7. Complete: links to the ACP and to your site.

After that the installer locks itself. Log in and go to the ACP (Admin Control Panel) at /admin.

Typed the wrong credentials? Nothing is written until the connection test passes, so fix them and hit Connect & save again. We never overwrite an existing .env; the wizard only adds the keys that are missing.

The installer applies the migrations. If you want to run them yourself while developing, use pnpm db:migrate.