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 [email protected]
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.
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.