Wiki.js

Wiki.js 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 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.