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:
- Install dependencies:
sudo apt update
sudo apt install -y curl build-essential mongodb-server
- Download and extract Wekan:
wget https://releases.wekan.team/wekan-latest.tar.gz
tar -zxvf wekan-latest.tar.gz -C /opt/
- 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.
