In the contemporary landscape of project management and collaborative software, the tension between centralized cloud services and decentralized self-hosted solutions has reached a critical inflection point. Organizations and individual technologists alike are increasingly wary of data sovereignty, privacy breaches, and the inherent limitations of proprietary SaaS platforms. In this context, WeKan emerges as a formidable open-source alternative, offering a fully featured Kanban board experience that prioritizes user control and data ownership. The deployment of WeKan via Docker represents the most robust, flexible, and scalable method for bringing this software into production environments. By leveraging containerization, administrators can isolate the application stack, manage dependencies with surgical precision, and ensure consistent performance across development, staging, and production environments. This guide provides an exhaustive technical examination of deploying WeKan using Docker, exploring everything from basic container initialization to complex swarm configurations, database migration strategies, and advanced security hardening. It is designed for the serious systems administrator, the DevOps engineer, and the tech enthusiast who demands complete mastery over their digital workspace.
The Philosophy and Architecture of WeKan
WeKan is not merely a clone of existing commercial Kanban tools; it is a distinct, free software solution built on the principles of transparency and user agency. The project explicitly encourages users to install the software on their own hardware, thereby eliminating the need to trust a third-party vendor with sensitive project data. This architectural decision aligns with the broader open-source movement’s goal of providing tools that are both powerful and privacy-respecting. The software is designed to handle a wide spectrum of use cases, from personal todo lists and holiday planning with friends to complex team collaborations on revolutionary ideas. The core value proposition lies in its visual overview capabilities, allowing users to focus on the most critical items by organizing tasks into columns and cards.
The open-source nature of WeKan is backed by rigorous standards. In November 2023, WeKan underwent an assessment against the Standard for Public Code. The project currently meets 8 out of 16 criteria out of the box, demonstrating a strong baseline of compliance with public sector and high-availability standards. While some additional criteria can be met with minor configuration changes, the default state of the software is already highly optimized for public and professional use. This commitment to quality extends to its localization strategy. Translations to non-English languages are managed exclusively through Transifex via a web browser interface, ensuring that the community can contribute to the software’s global reach without needing deep technical knowledge of the codebase. For developers contributing to the core English interface, new strings are added via pull requests to the master branch in the file wekan/imports/i18n/data/en.i18n.json. This structured approach to internationalization ensures consistency and reduces the risk of fragmented language files.
The WeKan project maintains a strict policy regarding community interaction and support. Users are strongly advised to submit questions, feature requests, and bug reports as GitHub issues rather than relying on chat platforms. This preference is rooted in the technical reality that chat histories scroll and details are lost, whereas GitHub issues provide a persistent, searchable, and version-controlled record of the project’s evolution. The project also maintains a FAQ section that users are expected to consult before seeking assistance. Furthermore, the maintainers have issued a clear directive regarding community behavior: do not feed trolls or spammers. This reflects the open-source community’s ongoing battle against bad actors and underscores the importance of maintaining a healthy, productive development environment.
Docker Hub and Image Management
The primary vessel for distributing WeKan in a containerized format is the Docker Hub organization wekanteam. This repository serves as the central hub for pulling the official WeKan images. The organization currently hosts two primary repositories. The main repository, labeled "Open-Source kanban," is updated frequently, with the latest build occurring as recently as six days prior to the current date. This repository has achieved significant traction, with over 10 million pulls and 210 stars, indicating widespread adoption and trust within the developer community. The image size is approximately 185.8 MB, a reasonable footprint for a full-stack application including the web server and necessary dependencies.
The second repository in the wekanteam organization is dedicated to a WeKan variant that includes a GPLv2 licensed Gantt chart. This addition is significant for teams that require timeline-based planning capabilities alongside traditional Kanban views. This specific image is slightly older in terms of recent updates, with the last update occurring one year ago, but it has still garnered over 10,000 pulls and 4 stars. The distinction between these two images allows users to choose their feature set based on their licensing requirements and functional needs. The main image is the recommended starting point for most users due to its frequent updates and broader feature set.
To retrieve the image, administrators use the standard Docker pull command. The specific command to fetch the latest version of the main WeKan image is:
bash
docker pull wekanteam/wekan
This command downloads the image layers from Docker Hub and stores them in the local Docker daemon’s cache. The image includes all necessary components to run the WeKan application, including the Node.js runtime, the Meteor framework, and the necessary configuration scripts. The use of the latest tag is supported and recommended for users who wish to stay on the newest release. The tag latest dynamically points to the most recent release tag, ensuring that users can easily upgrade to the newest features and security patches. However, in production environments, it is often prudent to pin to a specific version tag to avoid unexpected breaking changes during automated upgrades.
Installation via Snap: The Simplified Alternative
While Docker offers the most flexibility for custom configurations, the WeKan project also provides a Snap package for users who prefer a simpler, more automated installation process on Linux systems. Snap packages are self-contained software packages that include the application and all its dependencies, ensuring that the software runs consistently across different Linux distributions. The Snap version of WeKan includes automatic updates, reducing the maintenance burden on the administrator.
To install WeKan via Snap, the user must first ensure that Snapd is installed on their system. Snapd is the background service that manages Snap packages. If not already present, it can be installed by following the instructions provided in the official Snapcraft documentation. Once Snapd is running, the installation of WeKan is straightforward. The command to install the latest candidate version of WeKan is:
bash
sudo snap install wekan --channel=latest/candidate
This command downloads and installs the WeKan application along with its MongoDB database backend. After installation, the administrator must configure the root URL and port for the application. This is done using the snap set command. For example, to set the root URL to the server’s IP address and the port to 80, the following commands are used:
bash
sudo snap set wekan root-url="http://YOUR-IP-ADDRESS"
sudo snap set wekan port='80'
After configuring these variables, the WeKan server is ready for use. The first user to register on the system becomes the administrator. This user has access to the Admin Panel, which is located at the top right of the interface under the username dropdown. The Admin Panel provides critical management functions, including the ability to disable self-registration, manage users, and customize the layout with a custom logo. Subsequent users who register will be assigned the "Normal user" role. For public-facing installations, it is highly recommended to add SSL/TLS encryption to secure data in transit. The WeKan documentation suggests using Caddy, a modern web server that automatically handles HTTPS certificates, as a suitable reverse proxy for this purpose.
Advanced Docker Compose Configuration
For users who require greater control over their deployment, the Docker Compose method is the preferred approach. The official WeKan repository provides a docker-compose.yml file that serves as the blueprint for the application stack. This file defines the services required to run WeKan, including the application container itself and the database backend. In recent versions, the database backend has evolved to include FerretDB and PostgreSQL, reflecting a shift towards more modern and compatible database solutions. FerretDB acts as a MongoDB-compatible proxy, allowing WeKan to use PostgreSQL as its underlying storage engine while maintaining the MongoDB API that the application expects.
Before deploying via Docker Compose, it is essential to prepare the environment. This involves creating the necessary directories for persistent storage. Data persistence is critical for any database-driven application, as it ensures that project boards, tasks, and user accounts are not lost when the container is restarted or updated. The recommended directory structure is as follows:
bash
mkdir /var/data/wekan
cd /var/data/wekan
mkdir -p {wekan-db,wekan-db-dump}
These directories will be bind-mounted into the Docker containers to store the database files and backup dumps. The wekan-db directory will hold the actual database files, while wekan-db-dump is reserved for backup operations.
Next, the environment variables must be configured. These variables control the behavior of the WeKan application and its database. A configuration file, such as /var/data/config/wekan.env, should be created and populated with the following variables:
bash
MONGO_URL=mongodb://wekandb:27017/wekan
ROOT_URL=https://wekan.example.com
MAIL_URL=smtp://[email protected]:[email protected]:587/
MAIL_FROM="Wekan <[email protected]>"
BACKUP_NUM_KEEP=7
BACKUP_FREQUENCY=1d
The MONGO_URL variable points to the MongoDB-compatible service. Even if using FerretDB and PostgreSQL, the URL format remains similar, as FerretDB translates the MongoDB protocol. The ROOT_URL variable must match the domain or IP address that users will use to access the application. If using SSL, this should be set to https://. The MAIL_URL and MAIL_FROM variables are used for sending password reset emails and other notifications. The backup variables BACKUP_NUM_KEEP and BACKUP_FREQUENCY control the automatic backup schedule, ensuring that seven days of backups are retained with a daily frequency.
The docker-compose.yml file itself defines the services. For a standard deployment, the file includes the WeKan application service and the database service. In newer configurations, the database service may be split into FerretDB and PostgreSQL services. The application service depends on the database service and uses the environment variables defined in the .env file. The docker-compose.yml file can be customized to include additional services, such as a reverse proxy or a backup scheduler, to create a more robust production environment.
Docker Swarm and High Availability
For organizations requiring high availability and scalability, Docker Swarm provides a native clustering and orchestration solution. Deploying WeKan in a Docker Swarm cluster allows for automatic load balancing, service replication, and rolling updates. This is particularly useful for large teams or public-facing installations where uptime and performance are critical.
A typical Swarm deployment requires a pre-configured cluster with persistent shared storage. The storage must be accessible to all nodes in the cluster to ensure that the database and application data are consistent across all replicas. Traefik is often used as a reverse proxy and load balancer in these configurations. Traefik integrates seamlessly with Docker Swarm and can automatically discover and route traffic to WeKan services.
Security is a paramount concern in public-facing deployments. One recommended design pattern is to secure the WeKan UI behind traefik-forward-auth. This middleware handles authentication before the request reaches the WeKan application. This approach enhances privacy by ensuring that users cannot access the WeKan interface until they have successfully authenticated. This separation of concerns allows the administrator to use any identity provider compatible with traefik-forward-auth, such as OAuth providers or LDAP servers.
The Docker Compose file for a Swarm deployment follows the v3 syntax. It defines the WeKan service with replicas, constraints, and placement directives. The configuration file might look like this:
yaml
services:
wekan:
image: wekanteam/wekan
environment:
- MONGO_URL=mongodb://wekandb:27017/wekan
- ROOT_URL=https://wekan.example.com
networks:
- wekan-net
deploy:
replicas: 3
placement:
constraints:
- node.role == worker
This configuration ensures that three replicas of the WeKan application are running on worker nodes, providing redundancy and load distribution. The traefik-forward-auth service is configured separately to handle authentication requests. This architecture ensures that the WeKan application remains stateless with respect to authentication, delegating this responsibility to the proxy layer.
User Management and Collaboration Features
Once deployed, WeKan offers a rich set of collaboration features. Boards can have multiple members, allowing for easy collaboration. Administrators can add users to boards, granting them access to view and modify cards. This granular access control is essential for managing project permissions and ensuring that only authorized personnel can make changes.
Cards within a board can be assigned colored labels to facilitate grouping and filtering. This visual cue helps users quickly identify the priority, status, or category of a task. Additionally, users can be assigned to specific cards, clarifying responsibility and accountability. This feature is particularly useful in agile workflows where tasks are often reassigned during daily stand-ups or sprint planning.
The administration panel provides additional controls for managing the WeKan instance. Administrators can disable self-registration to prevent unauthorized users from creating accounts. This is a critical security measure for internal deployments. The admin panel also allows for the management of users, including the ability to reset passwords and change roles. Customization options, such as setting a custom logo, allow organizations to brand the WeKan instance to match their corporate identity.
Backup and Restore Procedures
Data integrity is the cornerstone of any production system. WeKan’s reliance on a database backend means that regular backups are essential to prevent data loss. The Docker Compose configuration includes variables for automatic backups, but manual backup and restore procedures are also necessary for disaster recovery scenarios.
The backup process involves dumping the MongoDB database. This can be done by entering the database container and running the mongodump command. The steps for creating a backup are as follows:
bash
docker exec -it wekan-db bash
cd /data
mongodump
exit
docker cp wekan-db:/data/dump .
This sequence enters the database container, runs the dump command to create a backup of the database, and then copies the dump file to the host filesystem. The dump file is stored in the wekan-db-dump directory, ensuring that it is preserved outside the container.
Restoring from a backup is a more delicate process. It requires stopping the WeKan application, removing the existing database files, copying the backup into the container, and then restoring the database. The steps for restoring are as follows:
bash
docker stop wekan-app
docker exec -it wekan-db bash
cd /data
rm -rf dump
exit
docker cp dump wekan-db:/data/
docker exec -it wekan-db bash
cd /data
mongorestore --drop
exit
docker start wekan-app
This sequence stops the application container, enters the database container, removes the existing dump directory, copies the new backup into the container, restores the database using mongorestore --drop, and finally restarts the application. The --drop option ensures that any existing data in the target database is cleared before the restore, preventing conflicts between the old and new data.
Container Maintenance and Debugging
Maintaining a Docker-based WeKan installation requires familiarity with standard container management commands. Administrators may need to enter the containers to debug issues or perform manual maintenance. The command to enter the WeKan application container is:
bash
docker exec -it wekan-app bash
Similarly, the command to enter the database container is:
bash
docker exec -it wekan-db bash
Once inside the container, administrators can inspect logs, check file permissions, or run diagnostic commands. For example, if the MongoDB database becomes corrupted, administrators may need to repair it. The WeKan documentation provides links to resources for repairing MongoDB issues, although this is a rare occurrence.
The status of running containers can be checked using the docker ps command. This command lists all running containers, their IDs, names, and status. To stop a container, the docker compose stop command is used. To start a container in the background, the docker compose up -d command is used. These commands form the basic toolkit for managing the WeKan deployment.
For users who prefer to run Docker as a system service, the standard system commands apply. On Systemd-based distributions like Ubuntu 16.04 and Debian 9, the Docker service can be enabled and started with:
bash
sudo systemctl enable docker
sudo systemctl start docker
On older init.d-based distributions like CentOS 6 and Ubuntu 14.04, the commands are:
bash
sudo update-rc.d docker defaults
sudo service docker start
Creating a dedicated user for Docker operations is also a recommended security practice. This user can be added to the Docker group to grant them permission to manage containers without requiring root access. The steps for creating a dedicated user are:
bash
sudo useradd -d /home/wekan -m -s /bin/bash wekan
sudo usermod -aG docker wekan
After creating the user, the administrator should log in as the wekan user and create the docker-compose.yml file in the home directory. This approach minimizes the risk of accidental system-wide changes and provides a cleaner separation of duties.
Conclusion
The deployment of WeKan via Docker represents a sophisticated yet accessible solution for organizations seeking to regain control over their project management tools. By leveraging the flexibility of containerization, administrators can tailor the deployment to their specific needs, whether that involves a simple single-server setup or a complex, high-availability Swarm cluster. The shift towards FerretDB and PostgreSQL as the backend database offers a modern, compatible alternative to traditional MongoDB, expanding the ecosystem of tools available for data storage and management. The emphasis on security, through measures like traefik-forward-auth and SSL/TLS encryption, ensures that sensitive project data remains protected. Furthermore, the robust backup and restore procedures provide a safety net against data loss, giving administrators the confidence to operate in a production environment. As the open-source community continues to contribute to WeKan’s development, adding new features and refining existing ones, the software stands as a testament to the power of collaborative, transparent software development. For the tech enthusiast, the DevOps engineer, and the privacy-conscious organization, WeKan in Docker is not just a tool, but a statement of sovereignty over one’s digital workflow.