How to Install Wiki.js on FreeBSD 11

Published on: Fri, May 10, 2019 at 11:07 am EST

Wiki.js is a free and open source, modern wiki app built on Node.js, MongoDB, Git and Markdown. Wiki.js source code is publicly hosted on Github. This guide will show you how to install Wiki.js on a fresh FreeBSD 11 Vultr instance by using Node.js, MongoDB, PM2, Nginx, Git and Acme.sh.

Requirements

Requirements to run Wiki.js are as follows:

  • Node.js version 6.11.1 or later
  • MongoDB version 3.2 or later
  • Git version 2.7.4 or later
  • A web server such as Nginx, Apache, IIS, Caddy, or H2O. This guide will use Nginx.
  • A Git-compliant repository (public or private) This is optional
  • A minimum of 512MB RAM. It is highly recommended to use a machine with at least 1GB of RAM.
  • Domain name with A/AAAA records set up. In this guide we will use wiki.example.com as an example domain.

Before you begin

Check the FreeBSD version.

uname -ro
# FreeBSD 11.2-RELEASE

Ensure that your FreeBSD system is up to date.

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

Install sudo, vim, unzip, wget, git, bash and socat packages if they are not present on your system.

pkg install -y sudo vim unzip wget git bash socat

Create a new user account with your preferred username (we will use johndoe).

adduser

# Username: johndoe
# Full name: John Doe
# Uid (Leave empty for default): <Enter>
# Login group [johndoe]: <Enter>
# Login group is johndoe. Invite johndoe into other groups? []: wheel
# Login class [default]: <Enter>
# Shell (sh csh tcsh nologin) [sh]: bash
# Home directory [/home/johndoe]: <Enter>
# Home directory permissions (Leave empty for default): <Enter>
# Use password-based authentication? [yes]: <Enter>
# Use an empty password? (yes/no) [no]: <Enter>
# Use a random password? (yes/no) [no]: <Enter>
# Enter password: your_secure_password
# Enter password again: your_secure_password
# Lock out the account after creation? [no]: <Enter>
# OK? (yes/no): yes
# Add another user? (yes/no): no
# Goodbye!

Run the visudo command and uncomment the %wheel ALL=(ALL) ALL line, to allow members of the wheel group to execute any command.

# Uncomment by removing the hash (#) sign
%wheel ALL=(ALL) ALL

Now, switch to your newly created user.

su - johndoe

NOTE: Replace johndoe with your username.

Set up the timezone.

sudo tzsetup

Install Node.js

Wiki.js requires Node.js 6.11.1 or later, so we will first need to install the appropriate version of Node.js.

Install Node.js and NPM.

sudo pkg install -y node8 npm-node8

Check the versions.

node -v && npm -v
# v8.12.0
# 6.4.1

Install MongoDB

Wiki.js uses MongoDB as a database engine.

Install MongoDB.

sudo pkg install -y mongodb36

Check the version.

mongo --version | head -n 1 && mongod --version | head -n 1
# MongoDB shell version v3.6.6
# db version v3.6.6

Enable and start MongoDB.

sudo sysrc mongod_enable=yes
sudo service mongod start

Install Acme.sh and obtain a Let's Encrypt certificate (optional)

Securing your wiki 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. That makes it very lightweight in comparison to some other Acme protocol clients that require a lot of dependencies to run successfully.

Download and install Acme.sh.

sudo mkdir /etc/letsencrypt
git clone https://github.com/Neilpang/acme.sh.git
cd acme.sh
sudo ./acme.sh --install --home /etc/letsencrypt --accountemail your_email@example.com
cd ~

Check the acme.sh version.

/etc/letsencrypt/acme.sh --version
# v2.8.0

Obtain RSA and ECDSA certificates for wiki.example.com.

# RSA 2048
sudo /etc/letsencrypt/acme.sh --issue --standalone --home /etc/letsencrypt -d wiki.example.com --ocsp-must-staple --keylength 2048
# ECDSA/ECC P-256
sudo /etc/letsencrypt/acme.sh --issue --standalone --home /etc/letsencrypt -d wiki.example.com --ocsp-must-staple --keylength ec-256

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

  • RSA: /etc/letsencrypt/wiki.example.com
  • ECC/ECDSA: /etc/letsencrypt/wiki.example.com_ecc

NOTE: Don't forget to replace wiki.example.com with your domain name.

After obtaining certificates from Let's Encrypt, we need to configure Nginx to take advantage of them.

Install and configure Nginx

Wiki.js can run without any actual web server, however it is highly recommended to put a standard web server in front of it. This ensures you can use features like SSL, multiple websites, caching and others. We will use Nginx in this tutorial, but any other server will do, you just need to configure it properly.

Install Nginx.

sudo pkg install -y nginx

Check the version.

nginx -v
# nginx version: nginx/1.14.0

Enable and start Nginx.

sudo sysrc nginx_enable=yes
sudo service nginx start

Configure Nginx as a HTTPS (if you use SSL) reverse proxy for the Wiki.js application.

Run sudo vim /usr/local/etc/nginx/wiki.js.conf and populate it with the basic reverse proxy configuration below.

server {

  listen [::]:443 ssl http2;
  listen 443 ssl http2;
  listen [::]:80;
  listen 80;

  server_name wiki.example.com;

  charset utf-8;
  client_max_body_size 50M;

  # RSA
  ssl_certificate /etc/letsencrypt/wiki.example.com/fullchain.cer;
  ssl_certificate_key /etc/letsencrypt/wiki.example.com/wiki.example.com.key;
  # ECDSA
  ssl_certificate /etc/letsencrypt/wiki.example.com_ecc/fullchain.cer;
  ssl_certificate_key /etc/letsencrypt/wiki.example.com_ecc/wiki.example.com.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 config above is the server_name directive, and potentially the proxy_pass directive if you decide to configure some port other than 3000. Wiki.js uses port 3000 by default. Save the file and exit with : + W + Q

Now we need to include the wiki.js.conf file in the main nginx.conf file.

Run sudo vim /usr/local/etc/nginx/nginx.conf and add the following line to the http {} block.

include wiki.js.conf;

Check the configuration.

sudo nginx -t

Reload Nginx.

sudo service nginx reload

Install Wiki.js

Create an empty document root folder where Wiki.js will be installed.

sudo mkdir -p /usr/local/www/wiki.example.com

Navigate to the document root folder.

cd /usr/local/www/wiki.example.com

Change ownership of /usr/local/www/wiki.example.com folder to user johndoe.

sudo chown -R johndoe:johndoe /usr/local/www/wiki.example.com

From the /usr/local/www/wiki.example.com folder, run the following commands to download and install Wiki.js.

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

VERSION=$(curl -L -s -S https://beta.requarks.io/api/version/stable)
curl -L -s -S https://github.com/Requarks/wiki/releases/download/v$VERSION/wiki-js.tar.gz | tar -f - -xz -C .
curl -L -s -S https://github.com/Requarks/wiki/releases/download/v$VERSION/node_modules.tar.gz | tar -f - -xz -C .
cp -n config.sample.yml config.yml

You can run the following command in order to view the currently installed version of Wiki.js.

node wiki --version
# 1.0.102

Once the installation is completed, you'll be prompted to run the configuration wizard.

Start the configuration wizard by running.

node wiki configure

This will notify you to navigate to http://localhost:3000 to configure Wiki.js. If you have Nginx in front of Wiki.js, then it means you can open your domain name (e.g. http://wiki.example.com) instead of going to localhost.

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

Install and setup PM2 process manager

By default, Wiki.js will not start automatically after a system reboot. In order to make it start on boot, we need to install and setup PM2 process manager.

Install PM2 globally via npm.

sudo npm install -g pm2

Check the version.

pm2 -v
# 3.2.2

Navigate to your document root folder if you are not already there and stop Wiki.js.

cd /usr/local/www/wiki.example.com
node wiki stop

Start Wiki.js via PM2.

pm2 start server/index.js --name "Wiki.js"

List process managed by PM2.

pm2 list

Tell PM2 to configure itself as a startup service by running:

pm2 startup

Finally, save the current PM2 configuration by running the command:

pm2 save

Your Wiki.js instance now runs as a background process, using PM2 as its process manager.