# Installation
Setup requirements:
▸ Fresh Ubuntu 20.04 LTS installation with SSH access
{.is-info}
## Setting up the webserver
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](https://nickjanetakis.com/blog/docker-tip-68-its-ok-not-to-use-docker-for-everything) 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`](https://stackoverflow.com/questions/45023363/what-is-docker-io-in-relation-to-docker-ce-and-docker-ee)?
``` sudo apt install docker.io ```
## Installing Wiki.js
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](https://docs.docker.com/network/network-tutorial-standalone/) to each other (default bridge network is discouraged to avoid ARP spoofing). Create a Docker volume `pgdata` for [data persistence](https://docs.docker.com/get-started/05_persisting_data/) 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](https://hub.docker.com/r/linuxserver/wikijs).
``` 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}
## Set up SSL connection to wiki
For configurations where Wiki.js is directly exposed to the internet, the [official setup instructions](https://docs.requarks.io/install/ubuntu) 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](https://certbot.eff.org/lets-encrypt/ubuntufocal-nginx) 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;
} ```
---
# Recommended initial configuration
## Restrict guest access permissions
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.
## Enable backup of wiki contents
This is *massively important*, see the section below on reinitializing the wiki when [locked out](#locked-out-from-wiki). At the moment, the default wiki export backs up the wiki contents only (database migration instructions can be found [here](https://docs.requarks.io/install/transfer)).
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.
## Change search engine provider
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](https://docs.requarks.io/en/search/postgres). More granularity seems to be available by [implementing definitions for search functions](https://docs.requarks.io/dev/search).
---
# Usage
The Markdown specification for Wiki.js is listed [here](https://docs.requarks.io/en/editors/markdown). The rules unique to Wiki.js is replicated below for convenience:
## {.tabset}
### Content tabs
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
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}
### Link list
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)](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}
# Troubleshooting
## Locked out from wiki
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](https://hub.docker.com/r/bitnami/postgresql/):
"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](https://docs.docker.com/engine/reference/commandline/volume_rm/):
``` 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](#enable-backup-of-wiki-contents).
## Editing redirects to wrong page source
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.
## "Timed out while waiting for handshake"
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.