Jul 11, 2024 3 min read

Wekan: Self-Hosting Made Simple

Wekan: Self-Hosting Made Simple
Table of Contents

Wekan is an open-source, self-hosted Kanban board application that allows teams to collaborate and manage tasks with ease. It is a highly customizable and lightweight alternative to proprietary services, giving users complete control over their data while offering robust features for project management. In this guide, we’ll walk you through installing, configuring, securing, managing, and leveraging Wekan’s unique features in a self-hosted environment.

Installing Wekan

πŸ“¦ Docker/Docker Compose Setup

Using Docker Compose is one of the simplest methods to deploy Wekan. Below is a docker-compose.yml file tailored to Wekan:


version: "3.7"

services:

wekandb:

image: mongo:5.0

container_name: wekandb

restart: always

volumes:

- wekan-db-data:/data/db

networks:

- wekan-net

wekan:

image: wekanteam/wekan:latest

container_name: wekan

restart: always

depends_on:

- wekandb

ports:

- "8080:8080"

environment:

- MONGO_URL=mongodb://wekandb:27017/wekan

- ROOT_URL=http://localhost

networks:

- wekan-net

volumes:

wekan-db-data:

networks:

wekan-net:

Save the above file as docker-compose.yml. Then, deploy Wekan using the following commands:


docker-compose up -d

## Check the status of the containers

docker-compose ps

This will start Wekan on port 8080, and MongoDB will handle the database.

πŸš€ Manual Installation

For advanced users, Wekan can also be installed manually on a Linux server. Here’s how:

  1. Install dependencies:

sudo apt update

sudo apt install -y curl build-essential mongodb-server

  1. Download and extract Wekan:

wget https://releases.wekan.team/wekan-latest.tar.gz

tar -zxvf wekan-latest.tar.gz -C /opt/

  1. Start Wekan:

cd /opt/bundle/programs/server

npm install

export MONGO_URL=mongodb://127.0.0.1:27017/wekan

export ROOT_URL=http://localhost

export PORT=8080

node main.js

Wekan will now be accessible on http://localhost:8080.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To serve Wekan with a custom domain, configure Nginx as a reverse proxy. Create a new Nginx configuration file, such as /etc/nginx/sites-available/wekan:


server {

listen 80;

server_name yourdomain.com;

location / {

proxy_pass http://127.0.0.1:8080;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection 'upgrade';

proxy_set_header Host $host;

proxy_cache_bypass $http_upgrade;

}

}

Enable the configuration and restart Nginx:


sudo ln -s /etc/nginx/sites-available/wekan /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your Wekan instance with Let's Encrypt:


sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com

Certbot will automatically configure SSL and enable HTTPS for your domain.

πŸ› οΈ Testing and Reloading Nginx

Validate the configuration and reload Nginx:


sudo nginx -t

sudo systemctl reload nginx

Test by accessing https://yourdomain.com.

Logging and Debugging Wekan

πŸ—ƒοΈ Enabling Debug Logs

Enable debug-level logging by setting the DEBUG environment variable:


export DEBUG=true

For Docker users, add it to the Wekan service in your docker-compose.yml:


environment:

- DEBUG=true

Restart the Wekan container:


docker-compose restart wekan

πŸ“„ Viewing Logs

For Docker deployments, view logs with:


docker logs -f wekan

For manual installations, check the logs in the terminal where Wekan is running or configure a logging directory.

πŸ› οΈ Troubleshooting Common Issues

If Wekan fails to start, verify the following:

  • MongoDB is running: sudo systemctl status mongodb

  • Environment variables are set correctly.

  • Logs don’t show any missing dependencies.

πŸ“€ Exporting Logs

To integrate Wekan logs with an ELK Stack, use Filebeat or another log shipper to forward logs to Elasticsearch.

Backup and Restore

πŸ—‚οΈ File-Based Backups

For Docker, back up the volumes:


docker run --rm --volumes-from wekandb -v $(pwd):/backup ubuntu tar cvf /backup/wekan-db-backup.tar /data/db

For manual installations, back up /opt/bundle and MongoDB data directories.

πŸ”„ Database Backups

Export MongoDB data:


mongodump --db wekan --out /backup/wekan-dump

Restore the database:


mongorestore --db wekan /backup/wekan-dump/wekan

πŸ“… Automated Backup Scripts

Set up a cron job to automate backups (example for Docker volumes):


0 2 * * * docker run --rm --volumes-from wekandb -v /path/to/backup:/backup ubuntu tar cvf /backup/wekan-db-backup-$(date +\%F).tar /data/db

Updating and Upgrading Wekan

⬆️ Updating Docker Images

Pull the latest Docker image and redeploy:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

Download the latest Wekan release:


wget https://releases.wekan.team/wekan-latest.tar.gz

tar -zxvf wekan-latest.tar.gz -C /opt/

Restart Wekan after replacing the old files.

πŸ” Checking for Updates

Check Wekan’s GitHub Releases for the latest version.

Leveraging Wekan’s Unique Features

πŸ”§ Enabling APIs

Activate APIs for integrations by editing your environment variables. For Docker:


environment:

- ENABLE_API=true

Test API endpoints using curl:


curl -X GET http://localhost:8080/api/boards --header "Authorization: Bearer YOUR_API_KEY"

🌟 Advanced Configurations

Integrate Wekan with third-party tools like Rocket.Chat by enabling Webhooks in the application settings. Customize Wekan further by modifying the settings.json file:


{

"webhookUrl": "https://chat.yourdomain.com/hooks/YOUR_WEBHOOK_ID",

"defaultBoardVisibility": "private"

}

Wrapping Up

This guide has provided a comprehensive walkthrough of deploying, configuring, and managing Wekan in a self-hosted environment. By following these steps, you can take full advantage of Wekan’s flexibility, robust features, and self-hosting benefits. Whether as a personal task board or a collaborative tool, Wekan is a powerful solution for organizing your workflow on your terms.

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.