Getting Started with Wikantik

Adapted from docs/admin/GettingStartedGuide.md in the Wikantik repository; current as of release 2.4.56.

This guide is for administrators and developers deploying Wikantik for the first time, and is the entry point to the rest of the admin docs. It walks you from a fresh clone to a running wiki you can log into, over two paths:

Path A — Docker Compose — the fastest way to a running instance. One config file, one command. Best for evaluating Wikantik or running it as an appliance.
Path B — Bare-metal Tomcat — runs the WAR in a local Tomcat against your own PostgreSQL. Best for development, debugging, and customization.

Both paths end at the same place: a wiki at http://localhost:8080/ where you log in as admin / admin123 and are immediately required to choose a new password. See First login.

Which should I pick? If you just want to see Wikantik running, use Path A — it needs only Docker. If you intend to change code, use Path B.

Before you start

Clone the repository and cd into it:

git clone <your-fork-or-mirror-url> wikantik
cd wikantik

Prerequisites

Path	You need
A — Docker	Docker Engine with the Compose plugin (`docker compose version`). Nothing else.
B — Bare metal	Java JDK 25+, Maven 3.9+, Node.js 20.19+ (or 22.12+) + npm, PostgreSQL 15+. Docker is also needed if you want `bin/deploy-local.sh` to start its local embedding container (see step 3).

Why Node for a Java app? The WAR build compiles the React frontend with Vite; mvn runs npm install + vite build automatically, so npm must be on your PATH. Verify the bare-metal toolchain in one shot:

java -version && mvn -version && node --version && npm --version && psql --version

Path A — Docker Compose (fastest)

The stack is two containers: PostgreSQL (the pgvector/pgvector:pg18 image; the vector extension is required by search and the Knowledge Graph) and the Wikantik app. bin/container.sh builds the app image from the Dockerfile (bin/container.sh build), and on first start the app container runs database migrations, seeds the admin account, and starts Tomcat. Path A uses the base compose file only (-e base); the default dev environment of bin/container.sh adds docker-compose.dev.yml, which builds Dockerfile.dev and bind-mounts a prebuilt wikantik-war/target/Wikantik.war, so it needs a Maven build first.

1. Create your `.env`

The compose files read a gitignored .env. Copy the template and set a real database password:

cp .env.example .env

Edit .env and change one required value:

POSTGRES_PASSWORD=CHANGEME   # ← set this to a real password

Everything else has a working default (POSTGRES_DB=wikantik, POSTGRES_USER=wikantik, WIKANTIK_BASE_URL=http://localhost:8080/). Leave them unless you have a reason to change them.

Heads-up: the same .env drives both deployment paths. The app connects to PostgreSQL as POSTGRES_USER / POSTGRES_PASSWORD, so whatever you set here is what the database is created with — keep them consistent.

2. Build and start

bin/container.sh build
bin/container.sh -e base up -d

The build (first time: several minutes — it compiles Java + the React frontend) tags the image wikantik:latest. up -d starts PostgreSQL, waits for it to be healthy, runs migrations, seeds the admin account, and starts the app. Watch progress with:

bin/container.sh -e base logs -f wikantik

On a fresh database the startup log ends with a first-login banner:

============================================================
 Wikantik first start: log in at http://localhost:8080/
   Username: admin
   Password: admin123
 You will be required to choose a new password on first login.
============================================================

3. Verify and log in

curl -fsS http://localhost:8080/api/health    # → 200 with a JSON health body

Open http://localhost:8080/ and continue to First login.

Managing the stack

bin/container.sh wraps docker compose for the canonical service set. Pass -e base to every command so it targets the same compose files as step 2:

bin/container.sh -e base ps                 # container status
bin/container.sh -e base logs -f            # follow app logs
bin/container.sh -e base down               # stop (keeps data volumes)
bin/container.sh -e base down --volumes     # stop AND delete the database — full reset

Run bin/container.sh --help for the other subcommands (restart, shell, psql, migrate, backup, restore, smoke-test).

Running alongside a bare-metal Tomcat already on 8080? Set WIKANTIK_HOST_PORT=18080 in .env and the container publishes there instead.

For production container deployment (the backup sidecar, remote hosts, reverse proxy, TLS), see Docker Deployment.

Path B — Bare-metal Tomcat

This path creates a PostgreSQL database, builds the WAR, and deploys it into a local Tomcat 11 that deploy-local.sh downloads and manages for you under tomcat/ (gitignored).

1. Create the database

bin/db/install-fresh.sh creates the database, the application role, installs pgvector, and runs all migrations (which seed the admin account). Run it as a PostgreSQL superuser. Choose an application password and remember it — you will put the same value in .env in step 3.

sudo -u postgres \
  DB_NAME=wikantik \
  DB_APP_USER=wikantik \
  DB_APP_PASSWORD='choose-a-real-password' \
  bin/db/install-fresh.sh --no-migrate-role

Notes:

DB_APP_USER=wikantik matches the POSTGRES_USER default in .env.example. Keep these the same or the app cannot connect.
--no-migrate-role runs migrations as the superuser and is the simplest choice for local development. For a production-grade least-privilege setup where a dedicated migrate role owns the schema, omit the flag and pass DB_MIGRATE_PASSWORD='…' instead. The script fails fast if you provide neither — that is intentional, so you make the ownership decision up front rather than hitting a "must be owner of table" error on a later migration.
The script is idempotent — safe to re-run.

2. Build the WAR

mvn clean install -DskipTests -T 1C

This builds every module and the React frontend (via npm). Use -DskipTests for the build itself; do not use -Dmaven.test.skip (that omits a test-jar other modules need and breaks the reactor).

3. Configure and deploy

bin/deploy-local.sh renders the Tomcat config (ROOT.xml, wikantik-custom.properties) from .env, downloads Tomcat and the PostgreSQL JDBC driver (42.7.14, from Maven Central) on first run, deploys the WAR, applies migrations, seeds the admin account, and starts Tomcat. Unless you set WIKANTIK_LOCAL_EMBEDDINGS=false in .env, it also starts a local Ollama embedding container on port 11434 through Docker. The first run pulls the roughly 600 MB qwen3-embedding:0.6b model, which is a download, not a hang; without an embedder the wiki falls back to BM25-only search.

On the very first run with no .env, it copies .env.example → .env and stops so you can set the password:

bin/deploy-local.sh
# → "POSTGRES_PASSWORD is unset or still the .env.example placeholder."

Edit .env and set POSTGRES_PASSWORD to the same value you used for DB_APP_PASSWORD in step 1, and confirm POSTGRES_USER=wikantik. Then re-run:

bin/deploy-local.sh

It finishes by starting Tomcat and printing a first-login banner:

===========================================
 Wikantik is starting at http://localhost:8080/

   First login:  admin / admin123
   You will be required to choose a new password on first login.
===========================================

4. Verify and log in

curl -fsS http://localhost:8080/api/health

Open http://localhost:8080/ and continue to First login.

Iterating

After the first setup, the fast redeploy loop is:

mvn clean install -DskipTests -T 1C
bin/redeploy.sh        # shutdown → swap WAR → apply pending migrations → startup

bin/redeploy.sh does apply any pending DB migrations (idempotently, via bin/db/migrate.sh — a no-op when there are none); what it skips is template materialisation, Tomcat upgrade logic, secrets validation, and dev-user seeding. Use bin/deploy-local.sh again only when you change .env, upgrade Tomcat, or need templates/secrets re-applied. Tomcat lifecycle:

tomcat/tomcat-11/bin/shutdown.sh
tomcat/tomcat-11/bin/startup.sh
tail -f tomcat/tomcat-11/logs/catalina.out

For the deeper reference (config file locations, JNDI, manual migration commands), see Developing with PostgreSQL.

A fresh install seeds exactly one account — admin / admin123 — flagged so that the first login requires choosing a new password before you can do anything else. This is by design: no Wikantik install ever runs with a known default credential past first contact.

Open http://localhost:8080/ and log in with admin / admin123.
You are immediately routed to a Set a new password screen. Until you complete it, the API rejects every other request with 403 PASSWORD_CHANGE_REQUIRED — this is expected, not a bug.
Enter admin123 as the current password and choose a new one. Password rules follow NIST 800-63B (length-based, with a common-password blocklist), so admin123 itself is rejected.
After the change you land on the wiki. That password is now yours; redeploys and restarts never reset it.

The same forced-change flow applies whenever an administrator sets or resets a user's password, and when the "forgot password" email issues a temporary one.

Forgot the local admin password during development? Reset it back to the seeded default with the one-liner documented at the top of bin/db/seed-users.sql, then log in and change it again.

Common first-build pitfalls

Symptom	Cause & fix
`install-fresh.sh` exits: "DB_MIGRATE_PASSWORD is not set"	You passed neither `--no-migrate-role` nor `DB_MIGRATE_PASSWORD`. For local dev, add `--no-migrate-role`.
App starts but can't connect to the database / login fails for everyone	`POSTGRES_USER`/`POSTGRES_PASSWORD` in `.env` don't match the `DB_APP_USER`/`DB_APP_PASSWORD` you created the database with. Make them identical.
`deploy-local.sh` exits: "POSTGRES_PASSWORD is unset or still the .env.example placeholder"	First run created `.env`; edit it, set a real `POSTGRES_PASSWORD`, re-run. This guard is what stops a config from shipping with a known default.
`npm not found` during the Maven build	Node.js 20.19+ (or 22.12+)/npm aren't installed or not on `PATH`. The WAR build needs them for the React frontend.
Port 8080 already in use	Container: set `WIKANTIK_HOST_PORT=18080` in `.env`. Bare metal: stop the other service, or change the Tomcat connector port.
`403 PASSWORD_CHANGE_REQUIRED` on every API call after first login	Working as designed — finish the forced password change (see First login).
Container won't start: pgvector / `vector` extension errors	The DB image must be `pgvector/pgvector` (the base compose pins it). Don't substitute a plain `postgres` image.
Login works, then random logouts	In production behind a proxy, set `wikantik.cookieAuthentication=true` (remember-me) and ensure cookies aren't `SameSite=Strict`. Not an issue for plain localhost.

Next steps

Now that you're running:

Add users and groups — admin panel at /admin (Users, Security).
Pull in external content — the connector framework at /admin/connectors syncs websites, RSS/Atom feeds, sitemaps, Google Drive, GitHub, and Confluence spaces into machine-managed derived pages, on a per-connector schedule, with reader-facing provenance. See Connectors.
Single Sign-On (Google/OIDC/SAML) — Single Sign-On.
Backups & disaster recovery — Backup and Recovery.
Production database workflow & migrations — Database Migrations, Developing with PostgreSQL.
API keys for agents and tools — API Keys; the MCP tool lists live in MCP Integration.
Cloud deployment — Cloud Deployment on AWS and GCP.
Agent/AI surfaces (MCP servers, REST API, SCIM) — MCP Integration, SCIM Provisioning, and the architecture map in docs/developer/ProjectReference.md.
Sending email (password resets, notifications) — Sending Email from the Wiki.

Welcome to Wikantik.

Cluster Hub: Wikantik Platform Development Hub: Architecture, MCP Protocols, and Agent Briefings (wikantik-development)