Using a Different System?
-
How to Install Wekan (Open Source Kanban) on Ubuntu 16.04
Wekan is a kanban board built with the Meteor JavaScript framework. It is considered an open source and self-hosted alternative to Trello, providing nearly the same features. It allows you to create card based “to-do” management lists. Wekan is very helpful to increase productivity when working in a collaborative environment. Wekan has a fully responsive web interface, and it is actively translated in many languages.
Prerequisites
- A Vultr CentOS 7 server instance.
- A sudo user.
For this tutorial, we will use wekan.example.com
as the domain name pointed towards the Vultr instance. Please make sure to replace all occurrences of the example domain name with the actual one.
Update your base system using the guide How to Update CentOS 7. Once your system has been updated, proceed to install the dependencies.
Install Node.js
Wekan only supports Node.js LTS version 4.8
. To install Node.js, we will use the node version manager. Install nvm
by running the installer script.
wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.33.4/install.sh | bash
To immediately start using nvm
, run this.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && /. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && /. "$NVM_DIR/bash_completion"
If nvm
has installed successfully, then you should be able to check its version.
[user@vultr ~]$ nvm --version
0.33.4
Install Node.js.
nvm install v4.8
Set the default version of Node.js.
nvm use node
If Node.js has installed successfully, then you should be able to check its version.
node -v
You will see this output.
[user@vultr ~]$ node -v
v4.8.4
NVM installs Node.js for the current user only. For Node.js to be accessible globally, run this.
n=$(which node);n=${n%/bin/node}; chmod -R 755 $n/bin/*; sudo cp -r $n/{bin,lib,share} /usr
Node.js in now available as /bin/node
.
[user@vultr ~]$ sudo which node
/bin/node
Install MongoDB
MongoDB is a free and open source NoSQL database server. Unlike traditional databases which use tables to organize their data, MongoDB is document-oriented and uses JSON-like documents without schemas. Wekan uses MongoDB to store its data.
Wekan is compatible only with MongoDB version 3.2
. MongoDB is not available in the default YUM
repository, so you will need to create a new repository file.
sudo nano /etc/yum.repos.d/mongodb-org-3.2.repo
Populate the file with the following content.
[mongodb-org-3.2]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/3.2/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-3.2.asc
Install MongoDB.
sudo yum install -y mongodb-org
Start the MongoDB server and enable it to start automatically.
sudo systemctl start mongod
sudo systemctl enable mongod
Securing the MongoDB instance
By default, there is no authentication enabled in a MongoDB server. Any user that has access to the terminal of the server will have full privileges on the MongoDB installation. To secure the database server and restrict the access of an unprivileged user, we will need to set up authentication on the server.
MongoDB provides a mongo
shell, which is used to run queries on MongoDB. Switch to the mongo
shell by typing.
mongo
Create a new MongoDB user with root privileges. You can use any username of your choice. Please make sure to replace the password.
db.createUser(
{
user: "admin",
pwd: "StrongAdminPassword",
roles: [ { role: "root", db: "admin" } ]
}
)
You should see following output.
[user@vultr ~]$ mongo
MongoDB shell version: 3.2.17
connecting to: test
Welcome to the MongoDB shell.
...
2017-09-29T20:42:29.042+0000 I CONTROL [initandlisten]
> db.createUser(
... {
... user: "admin",
... pwd: "StrongAdminPassword",
... roles: [ { role: "root", db: "admin" } ]
... }
... )
Successfully added user: {
"user" : "admin",
"roles" : [
{
"role" : "root",
"db" : "admin"
}
]
}
Exit the MongoDB command interface to the Linux terminal by pressing “Ctrl+C
“.
Edit the MongoDB configuration file.
sudo nano /etc/mongod.conf
Append the following line at the end of the file.
security:
authorization: enabled
Restart MongoDB so that the configuration change can take effect.
sudo systemctl restart mongod
Now that security has been enabled, you can test if it is working by switching to the mongo shell again using the mongo
command. This time, if you run a query, such as show dbs
to show the list of databases, you will see a message reporting failed authorization. Exit to the sudo
user again after testing the log-in as the new user you just created.
Log in as the administrator
user you just created.
mongo -u admin -p
Provide the password of the user for a successful log-in. Create a new user for the Wekan
database which will be used to store Wekan data.
use wekan
db.createUser(
{
user: "wekan",
pwd: "StrongPassword",
roles: ["readWrite"]
}
)
Make sure to change the StrongPassword
with a strong password. You will see the following output.
[user@vultr ~]$ mongo -u admin -p
MongoDB shell version: 3.2.17
Enter password:
connecting to: test
...
2017-09-29T20:52:32.450+0000 I CONTROL [initandlisten]
>
> use wekan
switched to db wekan
> db.createUser(
... {
... user: "wekan",
... pwd: "StrongPassword",
... roles: ["readWrite"]
... }
... )
Successfully added user: { "user" : "wekan", "roles" : [ "readWrite" ] }
Install Wekan
Check for the latest link to the Wekan release on Github as new releases are very frequent. Download the latest version of Wekan from Github replacing the link to the installer package.
cd ~
wget https://github.com/wekan/wekan/releases/download/v0.41/wekan-0.41.tar.gz
Extract the downloaded archive into a new directory named wekan
.
mkdir wekan
tar xzvf wekan-*.tar.gz -C wekan
Install Bzip2
, which is required to extract the Node.js dependencies.
sudo yum -y install bzip2
Install the Node.js dependencies.
cd wekan/bundle/programs/server && npm install
The Wekan server reads configurations from the environment variables. Run the following commands to set the configurations as environment variables.
export MONGO_URL='mongodb://wekan:StrongPassword@127.0.0.1:27017/wekan?authSource=wekan'
export ROOT_URL='http://wekan.example.com'
export MAIL_URL='smtp://user:pass@mail.example.com:25/'
export MAIL_FROM='wekan@example.com'
export PORT=4000
Make sure to replace the MongoDB password for the wekan
user you have created. Also, update the mail URL according to your SMTP server settings. If you do not have mail server ready, you can always change this configuration later. Open the firewall to allow port 4000
through the firewall.
sudo firewall-cmd --zone=public --add-port=4000/tcp --permanent
sudo firewall-cmd --reload
To immediately start the application.
cd ~/wekan/bundle
node main.js
You can now access the application by going to http://wekan.example.com:4000
. You will see the interface to log-in to the Wekan kanban board.
For production use, it is recommended to set up a reverse proxy to serve the application on the standard HTTP
port and a systemd
service to manage the application process. In this tutorial, we will use the Nginx web server as a reverse proxy, secured with a Let’s Encrypt free SSL.
Setting up the Nginx Reverse Proxy
Install the Nginx web server and Certbot, which is the client application for Let’s Encrypt CA.
sudo yum -y install certbot nginx
Before you can request the SSL certificates, you will need to allow port 80
and 443
through the firewall. Certbot will check the domain authority before issuing certificates.
sudo firewall-cmd --zone=public --add-service=http --permanent
sudo firewall-cmd --zone=public --add-service=https --permanent
Now that we are running Wekan on a standard HTTPS
port, we do not need to allow port 4000
through the firewall. Adjust the firewall to remove port 4000
.
sudo firewall-cmd --zone=public --remove-port=4000/tcp --permanent
sudo firewall-cmd --reload
Note: The domain name which you are using to obtain the certificates from the Let’s Encrypt CA must be pointed towards the server. The client verifies the domain authority before issuing the certificates.
Generate the SSL certificates.
sudo certbot certonly --standalone -d wekan.example.com
The generated certificates are likely to be stored in the /etc/letsencrypt/live/wekan.example.com/
directory. The SSL certificate will be stored as fullchain.pem
, and the private key will be stored as privkey.pem
.
Let’s Encrypt certificates expire in 90 days, so it is recommended to set up auto-renewal of the certificates using Cronjob. Cron is a system service which is used to run periodic tasks.
Open the cron job file.
sudo crontab -e
Add the following line at the end of the file.
30 5 * * * /usr/bin/certbot renew --quiet
The above cron job will run every day at 5:30 AM. If the certificates are due for expiration, it will automatically renew them.
Create a new virtual host.
sudo nano /etc/nginx/conf.d/wekan.example.com.conf
Populate the file with the following.
upstream wekan {
server 127.0.0.1:4000;
}
server {
listen 80;
listen [::]:80;
server_name wekan.example.com;
location / {
if ($ssl_protocol = "") {
rewrite ^ https://$server_name$request_uri? permanent;
}
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name wekan.example.com;
add_header Strict-Transport-Security "max-age=15768000";
ssl_certificate /etc/letsencrypt/live/wekan.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/wekan.example.com/privkey.pem;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS';
ssl_prefer_server_ciphers on;
ssl_stapling on;
ssl_stapling_verify on;
error_page 497 https://$host:$server_port$request_uri;
location / {
proxy_pass http://wekan;
proxy_http_version 1.1;
proxy_set_header Host $host:$server_port;
proxy_set_header Referer $http_referer;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Ssl on;
proxy_set_header X-Nginx-Proxy true;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_redirect off;
proxy_send_timeout 86400;
proxy_read_timeout 86400;
}
}
Replace wekan.example.com
with your actual domain name in the above configuration.
Restart Nginx so that the changes can take effect.
sudo systemctl restart nginx
Enable Nginx to automatically start at boot time.
sudo systemctl enable nginx
Setup the Systemd Service
Create a new user for the process.
sudo adduser wekan -s /usr/sbin/nologin -d /opt/wekan
Now move all the files to the /opt/wekan
directory.
sudo mv ~/wekan/* /opt/wekan/
Provide ownership of the files to the newly created user.
sudo chown -R wekan:wekan /opt/wekan
Wekan does not take data from any configuration file. Instead, it accesses it from environment variables. We will create a new file to store the environment variables. The file containing the environment variables will be passed through the Systemd
service.
Create a new file to store environment variables.
sudo nano /opt/wekan/config.env
Populate the file with the following content.
MONGO_URL='mongodb://wekan:StrongPassword@127.0.0.1:27017/wekan?authSource=wekan'
ROOT_URL='http://wekan.example.com'
MAIL_URL='smtp://user:pass@mail.example.com:25/'
MAIL_FROM='wekan@example.com'
PORT=4000
HTTP_FORWARDED_COUNT=1
Please make sure to replace the username
and password
.
Provide the ownership to the wekan
user.
sudo chown -R wekan:wekan /opt/wekan/config.env
Create a new service file for the Wekan systemd service.
sudo nano /etc/systemd/system/wekan.service
Populate the file with the following.
[Unit]
Description=Wekan Server
After=syslog.target
After=network.target
[Service]
Type=simple
Restart=on-failure
StartLimitInterval=86400
StartLimitBurst=5
RestartSec=10
ExecStart=/bin/node /opt/wekan/bundle/main.js
EnvironmentFile=/opt/wekan/config.env
ExecReload=/bin/kill -USR1 $MAINPID
RestartSec=10
User=wekan
Group=wekan
WorkingDirectory=/opt/wekan
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=Wekan
[Install]
WantedBy=multi-user.target
Save the file and exit from the editor. Now you can easily start Wekan.
sudo systemctl start wekan
To enable Wekan to automatically start at boot time.
sudo systemctl enable wekan
To check the status of Wekan service.
sudo systemctl status wekan
Wrapping Up
You can now access the Wekan instance on https://wekan.example.com
. Start by creating a new account. Once you have created the account, you can enable administrative access to the newly created user. Login to the MongoDB shell as the administrative user.
mongo -u wekan -p --authenticationDatabase "wekan"
Now select the wekan
database and update the object to promote the user to the admin user.
use wekan
db.users.update({username:'admin_user'},{$set:{isAdmin:true}})
Please make sure to replace admin_user
with the actual username of the user you created. From the admin interface, you will be able to disable self-registration and update SMTP settings.
Congratulations, you have successfully installed the Wekan Kanban board on your Vultr CentOS instance.
Want to contribute?
You could earn up to $300 by adding new articles
Suggest an update
Request an article