How to Install Wiki.js on FreeBSD 12

Wiki.js is an open-source, modern and powerful wiki app based on Node.js, Git, and Markdown. Wiki.js runs on the blazingly fast Node.js engine and is optimized to conserve CPU resources. Some of the Wiki.js features worth mentioning are:

Markdown editing, backed by Git
Lightweight, yet extremely powerful
Beautifully designed for the modern web
Integrated Access Control
Intuitive Assets Management
Built-in search engine

In this tutorial, we will walk you through the Wiki.js version 1 installation process on a FreeBSD 12 operating system by using NGINX as a reverse proxy server, MongoDB as a database server, PM2 as a process manager and optionally you can secure transport layer by using acme.sh client and Let’s Encrypt certificate authority to add SSL support.

Requirements

Requirements to run Wiki.js are the following:

Node.js 6.11.1 to 10.x
MongoDB version 3.2 or later.
Git version 2.7.4 or later.
Web Server software such as NGINX, Apache, Caddy, H2O…
An empty Git repository (optional).
Minimum of 512MB RAM. 1GB of RAM recommended.
About 300MB of disk space.
Domain name with A/AAAA DNS records set up.

Prerequisites

A FreeBSD 12 operating system.
A non-root user with sudo privileges.

Initial Steps

Check your FreeBSD version:

uname -ro
# FreeBSD 12.0-RELEASE

Set up the timezone:

tzsetup

Update your operating system packages (software). This is an important first step because it ensures you have the latest updates and security fixes for your operating system’s default software packages:

freebsd-update fetch install
pkg update && pkg upgrade -y

Install some essential packages that are necessary for basic administration of FreeBSD 12.0 operating system:

pkg install -y sudo vim unzip wget git bash socat gcc8 pkgconf vips

Step 1- Install Node.js and npm

Wiki.js is built on Node.js. We are going to install the latest recommended version for Wiki.js which is version 10 at the time of this writing.

Download and install the latest Long-Term Support (LTS) release of Node.js from the FreeBSD repo:

sudo pkg install -y node10 npm-node10

NOTE: npm is distributed with Node.js – which means that when you download Node.js, you automatically get npm installed on your system.

Check the Node.js and npm versions:

node -v && npm -v

Npm is a separate project from Node.js, and tends to update more frequently. As a result, even if you’ve just downloaded Node.js (and therefore npm), you’ll probably need to update your npm. Luckily, npm knows how to update itself! To update your npm, type this into your terminal:

sudo npm install -g npm@latest

This command will update npm to the latest stable version.

Re-check npm version with:

npm -v

And it should return the latest version number.

Step 2 – Install the MongoDB database

Wiki.js needs a database to store its data, and the current stable version of Wiki.js supports only MongoDB database engine. According to that, we will need to install the MongoDB database.

Download and install MongoDB database:

sudo pkg install -y mongodb40

Check the MongoDB version:

mongo --version | head -n 1 && mongod --version | head -n 1

Start and enable (set it to start on reboot) MongoDB service if not already started and enabled:

sudo sysrc mongod_enable=yes
sudo service mongod start

Step 3 – Install `acme.sh` client and obtain Let’s Encrypt certificate (optional)

Securing your website with HTTPS is not necessary, but it is a good practice to secure your site traffic. In order to obtain an SSL certificate from Let’s Encrypt, we will use acme.sh client. Acme.sh is a pure UNIX shell software for obtaining SSL certificates from Let’s Encrypt with zero dependencies.

Download and install acme.sh:

sudo pkg install -y acme.sh

Check acme.sh version:

acme.sh --version
# v2.8.2

Obtain RSA and ECC/ECDSA certificates for your domain/hostname:

# RSA 2048
acme.sh --issue --standalone -d example.com --keylength 2048
# ECDSA
acme.sh --issue --standalone -d example.com --keylength ec-256

If you want fake certificates for testing you can add --staging flag to the above commands.

To list your issued certs you can run:

acme.sh --list

Create folders to store your certs. We will use /etc/letsencrypt but it can be anything you prefer to store SSL certs.

mkdir -p /etc/letsencrypt/example.com
mkdir -p /etc/letsencrypt/example.com_ecc

Install/copy certificates to /etc/letsencrypt directory.

# RSA
acme.sh --install-cert -d example.com  
        --cert-file /etc/letsencrypt/example.com/cert.pem 
        --key-file /etc/letsencrypt/example.com/private.key 
        --fullchain-file /etc/letsencrypt/example.com/fullchain.pem 
        --reloadcmd "sudo systemctl reload nginx.service"
# ECC/ECDSA
acme.sh --install-cert -d example.com --ecc 
--cert-file /etc/letsencrypt/example.com_ecc/cert.pem 
--key-file /etc/letsencrypt/example.com_ecc/private.key 
--fullchain-file /etc/letsencrypt/example.com_ecc/fullchain.pem 
--reloadcmd "sudo systemctl reload nginx.service"

After running the above commands, your certificates and keys will be in:

For RSA: /etc/letsencrypt/example.com directory.
For ECC/ECDSA: /etc/letsencrypt/example.com_ecc directory.

All the certificates will be automatically renewed every 60 days.

After obtaining certs, exit from root user and return back to normal sudo user:

exit

Step 4 – Install and configure NGINX

Wiki.js (or any HTTP Node.js app) can run without any actual web server (such as NGINX or Apache). However, it is highly recommended to put a standard web server in front of Wiki.js. This ensures you can use features like SSL, multiple websites, caching, etc. We will use NGINX in this tutorial, but any other server will do, you just need to configure it properly.

Install Nginx package, by issue the following command:

sudo pkg install -y nginx

After the installation, you can verify the Nginx version by running:

nginx -v

Start and enable (set it to start on reboot) Nginx service:

sudo sysrc nginx_enable=yes
sudo service nginx start

Run sudo vim /usr/local/etc/nginx/wiki.js.conf

sudo vim /usr/local/etc/nginx/wiki.js.conf

and configure NGINX as an HTTPS reverse proxy.

server {
    
    listen [::]:443 ssl http2;
    listen 443 ssl http2;
    listen [::]:80;
    listen 80;
    
    server_name example.com;

    charset utf-8;
    client_max_body_size 50M;
ssl_certificate /etc/letsencrypt/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/example.com/private.key;
ssl_certificate /etc/letsencrypt/example.com_ecc/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/example.com_ecc/private.key; location / { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_next_upstream error timeout http_502 http_503 http_504; } }

The only thing you need to change in the above config is server_name directive, the domain name in the SSL file paths, and potentially proxy_pass directive if you decide to configure some other than 3000 port. Wiki.js uses port 3000 by default.

Run sudo vim /usr/local/etc/nginx/nginx.conf and add the below line to http {} block to include Wiki.js config.

include wiki.js.conf;

Check Nginx configuration for syntax errors:

sudo nginx -t

Reload Nginx service:

sudo service nginx reload

Step 5 – Install and setup Wiki.js

Create a document root directory where Wiki.js should reside in:

sudo mkdir -p /usr/local/www/wiki.js

Navigate to the document root directory:

cd /usr/local/www/wiki.js

Create a user for Wiki.js

sudo useradd -d /usr/local/www/wiki.js wikijs

Change ownership of the /usr/local/www/wiki.js directory to Wiki.js user:

sudo chown -R wikijs:wikijs /usr/local/www/wiki.js

From /usr/local/www/wiki.js directory, run the following command to fetch and install the latest Wiki.js application:

cd /usr/local/www/wiki.js
sudo su wikijs

curl -sSo- https://wiki.js.org/install.sh | bash

Once the installation is completed, you can run the following command in order to view the currently installed version of Wiki.js:

node wiki --version

Once the installation is completed, you’ll be prompted to launch the configuration wizard.

So, start the configuration wizard by running:

node wiki configure

Using your web browser, navigate to http://example.com and follow the on-screen instructions. All settings entered during the configuration wizard are saved in the config.yml file. The configuration wizard will automatically start Wiki.js for you.

First, you will see a welcome message. Click on the “Start” button: