# Wiki.js

Wiki.js is a modern wiki engine with a visual editor, Markdown support and Git sync

[Wiki.js](https://github.com/requarks/wiki) is an open source wiki written in Node.js. Upstream's supported Linux install is not a source build: you download the prebuilt release tarball (`wiki-js.tar.gz`, which already contains `node_modules` and the compiled assets), add a `config.yml`, and run `node server`. On Hatchbox you do the same from a small Git repository whose build script downloads and unpacks the release.

## Requirements

Create a PostgreSQL database on the app's Databases tab. Wiki.js reads the `DATABASE_URL` Hatchbox exposes and uses it in place of the host, user and password fields in `config.yml`.

## Repository

Create a new Git repository with the four files below, push it to its `main` branch and point Hatchbox at it. You are not deploying Wiki.js's source repository, so there is nothing to fork.

`package.json`, which tells Hatchbox to install Node.js (the release tarball replaces it with the real one during the build):

```
{
  "name": "wiki",
  "private": true
}
```

`.nvmrc`, so Hatchbox installs the Node.js 24 line Wiki.js's Docker image uses:

```
24
```

`config.yml`, which Wiki.js fills in from environment variables at startup using its `$(NAME)` syntax:

```
port: $(PORT)
bindIP: 0.0.0.0
db:
  type: postgres
  ssl: false
logLevel: $(LOG_LEVEL:info)
logFormat: default
dataPath: ./data
```

The build script in the next section is the fourth file.

## Environment Variables

```
WIKI_VERSION=2.5.315
```

`WIKI_VERSION` is the Wiki.js release to download. Check the [releases page](https://github.com/requarks/wiki/releases) for the latest 2.5.x version; the 3.0 betas do not ship a tarball. `DATABASE_URL` and `PORT` are set by Hatchbox.

## Build Scripts

### .hatchbox/build

```
#!/usr/bin/env bash
set -e

WIKI_VERSION="${WIKI_VERSION:-2.5.315}"

curl -fsSL -o wiki-js.tar.gz "https://github.com/requarks/wiki/releases/download/v${WIKI_VERSION}/wiki-js.tar.gz"
tar -xzf wiki-js.tar.gz
rm wiki-js.tar.gz

# Uploads and cache live in shared/data so they survive deploys
mkdir -p "$DIR/shared/data/content"
rm -rf data
ln -s "$DIR/shared/data" data
```

The tarball unpacks `server/`, `assets/`, `node_modules/` and `package.json` into the release directory next to your `config.yml`. The upstream docs only require an extra `npm rebuild sqlite3` for SQLite, which you are not using.

## Processes

Add one process on the Processes tab:

1. `web` on your web servers: `node server`

Wiki.js reads the port from `config.yml`, which takes it from the `PORT` environment variable.

## First Login

Open your domain. Wiki.js shows its setup wizard on the first visit: enter the administrator email and password and the site URL (`https://wiki.example.com`), then click Install. The wizard creates the database schema and the admin account.

## Notes

Wiki.js runs its database migrations on startup, so upgrading is a matter of changing `WIKI_VERSION` on the Environment tab and deploying. Read the release notes first.

`dataPath` holds the cache and the files of the Local File System storage target (`data/content`), which the build script keeps in `shared/data`. Page content itself is in PostgreSQL. Run a single web server unless you set `ha: true` in `config.yml`, which Wiki.js supports with PostgreSQL only.

The Git storage module shells out to `git`, which is already installed on Hatchbox servers.