WikiJS

Warning: Excessively old content!

Setup requirements: ▸ Fresh Ubuntu 20.04 LTS installation with SSH access {.is-info}

This section is provided as a refresher. As with new instances, update the existing software packages first:

sudo apt update
sudo apt install -y

Install the nginx-full webserver in order to service web requests, which also comes with WebDAV support. Bare-metal installation is preferred over Docker installation since it is much easier to reload server configuration changes. Other webservers like Apache are alternatives but configuration is a lot more difficult with higher boilerplate code.

sudo apt install nginx-full

Install docker.io to run Docker containers of Wiki.js. Why not ''%%docker.ce%%''?

sudo apt install docker.io

Wiki.js now officially supports only the PostgreSQL database. First, create the database secret key.

sudo mkdir -p /etc/wiki
openssl rand -base64 32 | sudo tee /etc/wiki/.db-secret

Create a Docker network wikinet to allow the database and wiki containers to communicate directly to each other (default bridge network is discouraged to avoid ARP spoofing). Create a Docker volume pgdata for data persistence beyond lifetime of the database container.

sudo docker network create wikinet
sudo docker volume create pgdata

Create the PostgreSQL Docker container. The database listens to port 5432 by default.

sudo docker create --name=db \
    -h db \
    -e POSTGRES_DB=wiki \
    -e POSTGRES_USER=wiki \
    -e POSTGRES_PASSWORD_FILE=/etc/wiki/.db-secret \
    -v /etc/wiki/.db-secret:/etc/wiki/.db-secret:ro \
    -v pgdata:/var/lib/postgresql/data \
    --restart=unless-stopped \
    --network=wikinet \
    postgres:11

Create the Wiki.js Docker container. Note that Wiki.js listens to port 3000 by default, so requests should be forwarded to this port. For reference of available command line arguments to the Docker container, see the repository documentation.

sudo docker create --name=wiki \
    -h wiki \
    -e DB_TYPE=postgres \
    -e DB_HOST=db \
    -e DB_PORT=5432 \
    -e DB_PASS_FILE=/etc/wiki/.db-secret \
    -v /etc/wiki/.db-secret:/etc/wiki/.db-secret:ro \
    -e DB_USER=wiki \
    -e DB_NAME=wiki \
    -e UPGRADE_COMPANION=1 \
    --restart=unless-stopped \
    --network=wikinet \
    -p 3001:3000 \
    requarks/wiki:2

The accompanying Wiki.js update companion helps monitor upgrades to the Wiki.js software.

sudo docker create --name=wiki-update-companion \
    -h wiki-update-companion \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    --restart=unless-stopped \
    --network=wikinet \
    requarks/wiki-update-companion:latest

Start the Docker containers to run the application and start port listening.

sudo docker start db
sudo docker start wiki
sudo docker start wiki-update-companion

Wiki.js only supports subdomain-level hosting (e.g. wiki.pyuxiang.com) as opposed to nesting in subdirectory (e.g. pyuxiang.com/wiki). Pass requests for the desired subdomain towards the localhost at the specified port 3001 in nginx.

# /etc/nginx/sites-available/default

server {
    listen 80;                            # IPv4 with HTTP
    listen [::]:80;                       # IPv6 with HTTP
    server_name wiki.pyuxiang.com;
    location / {
        proxy_pass http://127.0.0.1:3001;  # localhost port 3001
    }
}

Verify that the connection is working by visiting the subdomain on HTTP - a first-time setup administration page will appear. Complete this before proceeding.

If you see a 502 Bad Gateway error, chances are you created the Wiki.js Docker container but forget to run it. This happens because the server tries to connect to the specified container port, but the container is not listening to the port. {.is-info}

For configurations where Wiki.js is directly exposed to the internet, the official setup instructions includes an option to configure SSL directly on Wiki.js using Certbot. Since we are running Wiki.js behind an existing webserver nginx, SSL termination should be handled by the webserver instead: Wiki.js itself will not provision HTTPS access. {.is-info}

Use Certbot to automatically add a certificate for the wiki. Note that alternative installation using snap is also available. Certificate renewal is automatically handled by a cron job or systemd timer created by Certbot.

sudo apt install certbot
sudo certbot --nginx

If you’d like, let Certbot handle the HTTPS redirecting in the nginx configuration files for you. The final rules should look something like this:

# /etc/nginx/sites-available/default

server {
    if ($host = wiki.pyuxiang.com) {
        return 301 https://$host$request_uri;
    }
    listen 80;
    listen [::]:80;
    server_name wiki.pyuxiang.com;
}

server {
    listen 443;
    listen [::]:443;
    server_name wiki.pyuxiang.com;
    location / {
        proxy_pass http://127.0.0.1:3001;
    }
    ssl_certificate /etc/letsencrypt/live/wiki.pyuxiang.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.pyuxiang.com/privkey.pem;
}

Anonymous viewing is allowed in Wiki.js, controlled by the Guest group permissions under Administration > Groups.

Typically in non-production environments, it is a good idea to restrict access to guest accounts temporarily while you add content (in particular to avoid search engines from indexing sensitive content). A recommendation is to deny all read-write access to all content, then selectively enable permissions on more specific subdirectories.

This is massively important, see the section below on reinitializing the wiki when locked out. At the moment, the default wiki export backs up the wiki contents only (database migration instructions can be found here).

Under Administration > Storage, you can enable the backup routine, e.g. specify the private IP address of the SSH-enabled backup server for SFTP-based backups. This is triggered whenever the respective page is updated.

Not yet implemented for this wiki: instructions here are incomplete. {.is-warning}

The default search provider is very limited - only page title and description can be queried. Instructions to update the search provider is found here. More granularity seems to be available by implementing definitions for search functions.

The Markdown specification for Wiki.js is listed here. The rules unique to Wiki.js is replicated below for convenience:

This content itself is housed within a tab. To achieve this, annotate the header as a {.tabset}, e.g.

# {.tabset}
## First tab

Content of first tab

## Second tab

Content of second tab

Admonitions can be used to emphasize important information. This replaces the formatting for a typical blockquote demarcated using a plain leading >.

> Info
{.is-info}

> Success
{.is-success}

> Warning
{.is-warning}

> Danger
{.is-danger}

Info {.is-info}

Success {.is-success}

Warning {.is-warning}

Danger {.is-danger}

A list of links can also be prettified using the {.links-list} annotation.

- [Blog *Timeline of Posts *(coming soon)**](https://docs.requarks.io/editors/blog)
- [Code *Raw HTML*](https://docs.requarks.io/editors/code)
- [Markdown *Plain Text Formatting*](https://docs.requarks.io/editors/markdown)
- [Visual Editor *Rich-Text WYSIWYG*](https://docs.requarks.io/editors/visualeditor)
{.links-list}

• Blog //Timeline of Posts //(coming soon)%%**%%
• Code //Raw HTML//
• Markdown //Plain Text Formatting//
• Visual Editor //Rich-Text WYSIWYG// {.links-list}

Bugs in Wiki.js are inevitable, especially given how new is at the time of writing (MediaWiki on the other hand is pretty stable). Reset the entire wiki if you find yourself locked out of the wiki - modifying the database is also another possible alternative.

The main data is stored in the PostgreSQL database, which in this setup is mounted as the postgres Docker container. Note the commentary on data persistence in its README:

“If you remove the container all your data and configurations will be lost, and the next time you run the image the database will be reinitialized. To avoid this loss of data, you should mount a volume that will persist even after the container is removed.”

First stop all running containers and remove the PostgreSQL Docker container - volumes in use by containers cannot be removed:

docker stop wiki-update-companion
docker stop wiki
docker stop db
docker rm db

Reinitialize the volume for the database:

docker volume rm pgdata
docker volume create pgdata

Recreate the PostgreSQL container and start all containers:

# Create a new container
docker create --name=db -e POSTGRES_DB=wiki -e POSTGRES_USER=wiki -e POSTGRES_PASSWORD_FILE=/etc/wiki/.db-secret -v /etc/wiki/.db-secret:/etc/wiki/.db-secret:ro -v pgdata:/var/lib/postgresql/data --restart=unless-stopped -h db --network=wikinet postgres:11

# Restart the Wiki.js server
docker start wiki
docker start wiki-update-companion

You will be prompted to setup the wiki from scratch once again - this endeavour will be a lot less painful if you have been backing up your wiki.

This erroneous behaviour has been previously observed, where the wrong page source is loaded when the edit button for another page is selected.

While the behaviour is not yet throughly replicated, do avoid editing content on multiple tabs to prevent this bug. Wiki.js is not designed for concurrent editing.

This message can occur when creating a page. This is an SSH error, which likely means your SSH backup settings are wrong. This also implies the backup is performed immediately when pages are editing / created.