Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Task/Project Management Wekan

Introduction

Welcome to this comprehensive guide on self-hosting Wekan, a powerful and flexible open-source Kanban board application. If you're looking for a way to manage tasks and projects visually, collaboratively, and with full control over your data, self-hosting Wekan is an excellent choice. This guide is designed for university students and anyone interested in learning the intricacies of deploying, managing, and utilizing a self-hosted application, taking you from basic setup to advanced configurations.

What is Wekan?

Wekan is an open-source project management tool based on the Kanban methodology. Kanban visualizes workflow using boards, lists, and cards.

• Boards: Typically represent a project, a team, or a specific workflow.
• Lists: Represent stages in a workflow (e.g., "To Do", "In Progress", "Done").
• Cards: Represent individual tasks or items that move across lists as they progress. Wekan allows users to create boards, define lists (stages), and manage tasks (cards) with features like assignments, labels, checklists, due dates, attachments, and comments. Being open-source means its code is publicly accessible, allowing for transparency, community contributions, and the possibility of modification.

Why Self-Host Wekan?

While many SaaS (Software as a Service) Kanban solutions exist (like Trello or Asana), self-hosting Wekan offers distinct advantages:

• Data Control & Privacy: Your project data resides entirely on your own server infrastructure. This is crucial for sensitive projects, compliance requirements (like GDPR), or simply for maintaining digital sovereignty. You are not subject to the terms of service or privacy policies of a third-party provider regarding your core project data.
• Customization: While Wekan's core is robust, self-hosting allows for deeper customization, potentially including theming (if supported), integrations via API and webhooks, and control over authentication methods.
• No Vendor Lock-in: You are not tied to a specific provider's ecosystem or pricing plans. You can migrate your data and application as needed.
• Cost: While you need to provide the server infrastructure (which could be a cheap VPS, a Raspberry Pi, or existing hardware), there are no recurring subscription fees for the Wekan software itself. This can be significantly more cost-effective for large teams or long-term use compared to per-user pricing models.
• Learning Opportunity: Self-hosting provides invaluable hands-on experience with server administration, application deployment (Docker, Snaps), database management (MongoDB), security practices (reverse proxies, HTTPS), and backup strategies – skills highly relevant in computer science and IT fields.

Prerequisites

To follow this guide effectively, you should have:

• Basic Linux Command Line Familiarity: Understanding how to navigate directories (cd), list files (ls), edit text files (e.g., using nano or vim), manage packages (apt), and manage services (systemctl). We will primarily use Ubuntu/Debian examples.
• Conceptual Understanding of Servers: Knowing what a server is, the difference between local and remote access (SSH), and basic networking concepts (IP addresses, ports).
• Server Access: You need a server environment to install Wekan. This could be:
  • A Virtual Private Server (VPS) from a cloud provider (DigitalOcean, Linode, Hetzner, AWS EC2, etc.).
  • A local virtual machine (using VirtualBox, VMware) running a Linux distribution like Ubuntu Server.
  • A dedicated server or even a Raspberry Pi (performance may vary).
• Understanding of Installation Methods (Conceptual): Familiarity with what containerization (Docker) or package management systems (Snaps) are is helpful, although we will guide you through the steps.

Overview of the Guide Structure

This guide is divided into three main levels, followed by a conclusion:

1. Basic: Covers the essentials – installing Wekan using common methods and navigating the fundamental user interface elements.
2. Intermediate: Focuses on multi-user setups, permissions, and leveraging more advanced board features for better workflow management.
3. Advanced: Delves into crucial operational aspects like backups, security hardening, updates, and further customization options like email notifications and templates.

Each numbered section includes theoretical explanations followed by a hands-on Workshop designed to reinforce the concepts through practical, step-by-step exercises based on relatable scenarios. Let's begin your journey into self-hosting Wekan!

1. Getting Started with Wekan Installation

This section covers the initial steps to get your own Wekan instance up and running. We will explore different installation methods and guide you through the process.

Choosing an Installation Method

Wekan offers several ways to install it. The most common and recommended methods for self-hosting are Snap and Docker. Let's compare them:

• Snap:
  • Pros: Simplest installation method, especially on Ubuntu and other Snap-supported distributions. Handles dependencies (like Node.js, MongoDB) internally. Offers automatic updates (can be configured). Managed by Canonical.
  • Cons: Less flexible configuration compared to Docker. Can sometimes lag behind the latest Wekan releases. File system abstraction can make direct access to data/config files slightly less intuitive. Primarily tied to systems supporting Snapd.
• Docker:
  • Pros: Highly flexible configuration using docker-compose.yml. Environment agnostic (runs anywhere Docker runs - Linux, macOS, Windows). Easy to manage specific versions of Wekan and MongoDB. Isolates Wekan and its database dependency cleanly. Easier integration into existing Docker-based infrastructure. Generally preferred for production setups due to control.
  • Cons: Requires installing Docker and Docker Compose first. Steeper learning curve initially compared to Snap if you're unfamiliar with Docker concepts (images, containers, volumes, networking). Requires manual updates (pulling new images and restarting containers).
• Source:
  • Pros: Maximum control over the build process and dependencies. Access to the absolute latest code (potentially unstable). Good for development or specific customization needs.
  • Cons: Most complex installation method. Requires manual management of Node.js, MongoDB, and all dependencies. Updates require manual fetching, rebuilding, and restarting. Prone to dependency conflicts. Generally not recommended for standard deployment unless you have specific needs and expertise.

Recommendation:

• For beginners or those wanting the quickest setup on Ubuntu, Snap is a good starting point.
• For more control, flexibility, production environments, or if you're already using Docker, Docker is the recommended path.
• Source installation is typically reserved for developers contributing to Wekan or those with very specific integration requirements.

This guide will provide detailed steps for both Snap and Docker installations.

System Requirements

Wekan itself is relatively lightweight, but the requirements depend on the number of users, boards, and activity. MongoDB (the database) is often the more resource-intensive component.

• Operating System: A recent Linux distribution is recommended (Ubuntu 20.04/22.04 LTS, Debian 11/12 are excellent choices). Other systems might work, especially with Docker.
• RAM: Minimum 1GB RAM is often cited, but 2GB RAM is strongly recommended for smoother operation, especially with a few active users or larger boards. More RAM is better for larger deployments.
• CPU: 1 vCPU is the minimum, but 2 vCPUs are recommended for better responsiveness.
• Disk Space: At least 10-20GB of disk space is advisable to accommodate the OS, Wekan installation, database growth, and uploaded attachments. SSDs significantly improve performance.

These are general guidelines. Monitor your server's resource usage after installation and scale up if necessary.

Installing Wekan using Snap

This method is straightforward on systems with Snapd installed (like Ubuntu Desktop and Server).

1. Install Snapd (if necessary)

On most recent Ubuntu versions, Snapd is pre-installed. On Debian or other distributions, you might need to install it first.

# For Debian/Ubuntu
sudo apt update
sudo apt install snapd
sudo snap install core # Installs the core snap runtime

Log out and log back in, or restart your system, to ensure snap's paths are updated correctly.

2. Install Wekan Snap

sudo snap install wekan

This command downloads and installs the Wekan snap package along with its bundled dependencies, including MongoDB.

3. Basic Snap Configuration (Optional but Recommended)

Wekan needs to know the URL it will be accessed from. Even if accessing locally initially, setting it is good practice. Replace your-server-ip-or-domain.com with your server's IP address or domain name. If just testing locally on the machine itself, you can use localhost. Wekan via Snap typically runs on port 80 by default if available, but this can vary or be configured. Let's explicitly set a port and the root URL. Wekan Snap documentation often suggests setting the port via the snap set command.

# Example: Set Wekan to run on port 3001 and set the ROOT_URL
sudo snap set wekan port='3001'
sudo snap set wekan root-url='http://your-server-ip-or-domain.com:3001'

# Example for local access only:
# sudo snap set wekan port='3001'
# sudo snap set wekan root-url='http://localhost:3001'

# After setting options, restart the Wekan services managed by Snap
sudo systemctl restart snap.wekan.wekan

Note: Check the specific documentation for the Wekan snap (snap info wekan) as configuration options might change. Sometimes the Snap might default to port 80 and configure ROOT_URL automatically based on that. If port 80 is already in use, you must set a different port.

4. Access Wekan

Open your web browser and navigate to the ROOT_URL you configured (e.g., http://your-server-ip-or-domain.com:3001 or http://localhost:3001).

You should see the Wekan login/registration page. The first user to register automatically becomes the administrator.

Installing Wekan using Docker

This method provides more control and uses Docker Compose to manage the Wekan application container and its MongoDB database container.

1. Install Docker and Docker Compose

Follow the official Docker documentation for your Linux distribution. Here's a summary for Ubuntu/Debian:

# Uninstall old versions (if any)
sudo apt-get remove docker docker-engine docker.io containerd runc

# Set up Docker's apt repository
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Verify Docker installation
sudo docker run hello-world

# Add your user to the docker group to run docker commands without sudo (optional)
# Log out and log back in for this change to take effect
sudo usermod -aG docker $USER
newgrp docker # Apply group change immediately in the current shell

Note: The official Docker documentation is the definitive source for installation instructions.

2. Create a Docker Compose Configuration File

Docker Compose uses a YAML file (docker-compose.yml) to define multi-container applications.

Create a directory for your Wekan configuration:

mkdir ~/wekan-docker
cd ~/wekan-docker

Create a file named docker-compose.yml using a text editor (like nano):

nano docker-compose.yml

Paste the following content into the file. Read the comments carefully and adjust the ROOT_URL and ports as needed.

version: '3.8' # Use a recent version compatible with your Docker Compose

services:
  wekan-db:
    image: mongo:6.0 # Use a specific, recent MongoDB version
    container_name: wekan-db
    restart: unless-stopped
    command: mongod --logpath /dev/null --oplogSize 128 --quiet # Basic command, consider adding --wiredTigerCacheSizeGB <value> based on RAM
    networks:
      - wekan-network
    volumes:
      - wekan-db-data:/data/db # Persistent storage for database files
      - wekan-db-dump:/dump # Optional: Volume for database dumps/backups
    expose:
      - 27017 # Expose port only to other containers on the network
    healthcheck:
        test: echo 'db.runCommand("ping").ok' | mongo wekan-db:27017/test --quiet
        interval: 10s
        timeout: 5s
        retries: 5
        start_period: 30s

  wekan:
    image: wekanteam/wekan:latest # Or specify a version tag like wekanteam/wekan:v7.38
    container_name: wekan-app
    restart: unless-stopped
    networks:
      - wekan-network
    ports:
      - "3001:8080" # Map host port 3001 to container port 8080 (Wekan's default internal port)
                    # Change 3001 if that port is busy on your host
    environment:
      - MONGO_URL=mongodb://wekan-db:27017/wekan # Connect to the db service on the internal network
      - ROOT_URL=http://your-server-ip-or-domain.com:3001 # IMPORTANT: Set this to your accessible URL!
      # Optional Email Configuration (See Advanced Section)
      # - MAIL_URL=smtp://user:pass@host:port/
      # Optional Disable Self-Registration (after first admin user is created)
      # - REGISTER_DISABLED=true
      # Optional: Increase RAM for Node.js process if needed (e.g., 1GB)
      # - NODE_OPTIONS=--max_old_space_size=1024
    depends_on:
      wekan-db:
        condition: service_healthy # Wait for the database to be healthy
    volumes:
      - wekan-data:/data # Persistent storage for attachments/avatars (optional, depending on Wekan version/config)

volumes:
  wekan-db-data: # Define the named volume for MongoDB data
    driver: local
  wekan-db-dump: # Define the named volume for dumps
    driver: local
  wekan-data: # Define the named volume for Wekan data (if used)
    driver: local

networks:
  wekan-network: # Define the bridge network for containers to communicate
    driver: bridge

Explanation of docker-compose.yml:

• version: '3.8': Specifies the Docker Compose file format version.
• services:: Defines the containers that make up the application.
  • wekan-db:: Defines the MongoDB container.
    • image: mongo:6.0: Specifies the official MongoDB image, version 6.0. Using specific versions is better than latest for stability.
    • container_name: wekan-db: Assigns a fixed name to the container.
    • restart: unless-stopped: Ensures the container restarts automatically unless manually stopped.
    • command: Starts MongoDB, reduces logging verbosity (--quiet, --logpath /dev/null), sets oplog size. Consider adding --wiredTigerCacheSizeGB to limit MongoDB's RAM usage (e.g., half your available RAM).
    • networks: [wekan-network]: Connects the container to our custom network.
    • volumes: [wekan-db-data:/data/db, wekan-db-dump:/dump]: Maps named Docker volumes to directories inside the container. wekan-db-data persists the database files, wekan-db-dump can be used for backups. Named volumes are managed by Docker and are the preferred way to persist data.
    • expose: [27017]: Makes port 27017 accessible to other containers on wekan-network, but not directly from the host machine.
    • healthcheck: Defines a command Docker uses to check if the MongoDB service is ready before starting the Wekan app container.
  • wekan:: Defines the Wekan application container.
    • image: wekanteam/wekan:latest: Specifies the official Wekan image. Consider pinning to a specific version tag (e.g., v7.38) for predictable updates.
    • container_name: wekan-app: Assigns a fixed name.
    • restart: unless-stopped: Automatic restarts.
    • networks: [wekan-network]: Connects to the same network as the database.
    • ports: ["3001:8080"]: Maps port 3001 on your host machine to port 8080 inside the Wekan container (where Wekan listens by default). If host port 3001 is busy, change the first number (e.g., "8081:8080").
    • environment:: Sets environment variables inside the Wekan container.
      • MONGO_URL: Tells Wekan how to connect to the database container (wekan-db is resolvable on the wekan-network). The /wekan part specifies the database name to use within MongoDB.
      • ROOT_URL: Crucial! Set this to the exact URL users will use to access Wekan in their browser (including the port if not standard 80/443). Incorrect ROOT_URL causes issues with routing, logins, and email links.
    • depends_on: Ensures the wekan-db container is healthy before starting the wekan container.
    • volumes: [wekan-data:/data]: Optionally map a volume for persistent data like attachments if Wekan configuration requires it (check Wekan docs for specifics on attachment storage).
• volumes:: Declares the named volumes used for persistent data storage. Docker manages these volumes.
• networks:: Declares the custom bridge network, allowing containers to communicate using their service names (wekan-db, wekan).

3. Run Wekan using Docker Compose

Navigate to the directory containing your docker-compose.yml file (~/wekan-docker) in your terminal and run:

docker compose up -d

• docker compose up: Reads the docker-compose.yml file, creates the network and volumes (if they don't exist), pulls the specified images (if not already downloaded), and starts the containers defined in the services section.
• -d: Runs the containers in detached mode (in the background), so you get your terminal prompt back.

You can check the status of your containers:

docker compose ps

You can view the logs (useful for troubleshooting):

# View logs for both containers (follow mode)
docker compose logs -f

# View logs for a specific container (e.g., wekan-app)
docker compose logs -f wekan-app

4. Access Wekan

Open your web browser and navigate to the ROOT_URL you configured in the docker-compose.yml file (e.g., http://your-server-ip-or-domain.com:3001).

You should see the Wekan login/registration page. The first user to register automatically becomes the administrator.

Workshop Your First Wekan Instance

Goal: Install Wekan using your chosen method (Snap or Docker) on a suitable environment and perform the initial user registration.

Scenario: You need a personal Kanban board to manage your university coursework and side projects. You'll set up Wekan on a test environment (like a local Virtual Machine running Ubuntu Server 22.04 or a small VPS).

Steps:

1. Prepare Your Environment:

   • Set up your chosen server environment (VM, VPS). Ensure it meets the minimum system requirements (at least 1GB RAM, preferably 2GB, 1-2 CPUs, 10-20GB disk).
   • Ensure you have SSH access or console access to the server.
   • Update your system: sudo apt update && sudo apt upgrade -y.

2. Choose Installation Method: Decide whether you want to use Snap or Docker based on the pros and cons discussed earlier.

3. Follow Installation Steps:

   • If using Snap:
     1. Verify/Install Snapd: sudo apt install snapd (if needed), sudo snap install core. Log out/in if required.
     2. Install Wekan: sudo snap install wekan.
     3. Configure Port and ROOT_URL: Choose a port (e.g., 3001) and set the URL. Use localhost if accessing only from the server itself, or the server's IP address if accessing from another machine on the same network.

        sudo snap set wekan port='3001'
        sudo snap set wekan root-url='http://<your-server-ip>:3001' # Or http://localhost:3001
        sudo systemctl restart snap.wekan.wekan
        

   • If using Docker:
     1. Install Docker and Docker Compose following the official instructions or the steps provided earlier. Add your user to the docker group or use sudo.
     2. Create the directory: mkdir ~/wekan-docker && cd ~/wekan-docker.
     3. Create the docker-compose.yml file (nano docker-compose.yml) with the provided content.
     4. Crucially, edit the ROOT_URL in docker-compose.yml to match your server's IP and the host port you chose (e.g., http://<your-server-ip>:3001). Ensure the host port (3001 in "3001:8080") is not already in use on your server.
     5. Start the containers: docker compose up -d.
     6. Check status: docker compose ps. Verify both wekan-db and wekan-app are running. Check logs if needed: docker compose logs -f wekan-app.

4. Verify Installation:

   • Open a web browser on a machine that can access your server (or the server itself if using localhost).
   • Navigate to the ROOT_URL you configured (e.g., http://<your-server-ip>:3001).
   • You should see the Wekan "Sign in / Register" page.

5. Create First Admin User:

   • Click on "Register".
   • Fill in your desired username, email address, and a strong password.
   • Click the "Register" button.
   • Since this is the first user, Wekan automatically grants this account administrative privileges.
   • You should be logged in and see the main Wekan dashboard (initially empty).

Congratulations! You have successfully installed and accessed your self-hosted Wekan instance.

2. Navigating the Wekan Interface

Now that Wekan is installed, let's familiarize ourselves with its core components and how to interact with them. Wekan uses the Kanban paradigm, which is intuitive once you understand the basic building blocks.

Understanding the Dashboard

When you first log in (after creating your initial board), you'll typically land on the Wekan Dashboard. This view provides an overview of:

• Your Boards: Boards you are a member of or have created.
• Templates: Reusable board structures you can create (covered later).
• Public Boards: Boards explicitly set to be visible to anyone (use with caution).
• Possibly other sections depending on configuration and version.

From the dashboard, you can quickly jump into any of your boards or create new ones. There's usually a prominent button like "+ Create New Board". The header bar typically contains links to the dashboard, your profile/settings, and notifications.

Boards Lists and Cards Explained

These are the three fundamental elements of Wekan's Kanban system:

• Boards:
  • Concept: A board represents a distinct project, workflow, team space, or area of responsibility. Think of it as the highest-level container for a specific set of tasks. Examples: "Website Redesign Project", "Thesis Research", "Personal Tasks Q3", "Team Alpha Sprint Board".
  • Creation: Typically created from the Dashboard using a "+ Create New Board" button. You'll give it a title and initially decide if it's public or private.
• Lists:
  • Concept: Lists represent the distinct stages or steps within the workflow defined by the board. They are displayed as vertical columns on the board. Cards (tasks) move from left to right (usually) through these lists as they progress.
  • Common Examples:
    • Simple: "To Do", "In Progress", "Done"
    • Software Dev: "Backlog", "Selected for Dev", "In Progress", "Code Review", "Testing", "Deployed"
    • Content Creation: "Ideas", "Drafting", "Editing", "Published"
  • Creation/Management: Within a board, you can add new lists (usually an "Add List" button/area on the right), rename existing lists, and reorder them by dragging and dropping.
• Cards:
  • Concept: Cards represent individual tasks, work items, ideas, bugs, or any unit of work that needs to be tracked through the workflow (lists). They are the items that move across the board.
  • Creation: Within a list, there's typically a "+ Add Card" button or link at the bottom. You start by giving the card a title.
  • Movement: The core Kanban action is dragging and dropping cards from one list to another as their status changes.

Card Elements

Clicking on a card opens its details view, revealing a wealth of information and collaborative features:

• Title: The primary identifier of the task. Should be concise and descriptive.
• Description: A more detailed area to explain the task, provide context, links, or acceptance criteria. Supports Markdown formatting for richer text.
• Members: Assign one or more board members responsible for the card. Assigned members often get notifications related to the card.
• Labels: Colored tags used to categorize, prioritize, or flag cards. You can define labels at the board level (e.g., "Bug", "Feature", "Urgent", "Question") and apply multiple labels to a card. Useful for filtering and quick visual identification.
• Checklists: Break down a larger task into smaller, actionable sub-tasks. Each item in a checklist can be checked off as it's completed, showing a progress bar for the checklist. You can add multiple checklists to a single card.
• Attachments: Upload files directly to the card (e.g., documents, images, mockups). Check your Wekan/server configuration regarding attachment storage limits and location.
• Comments: A threaded discussion area for collaboration on the specific task. Members can ask questions, provide updates, or give feedback. Supports mentioning other users (@username).
• Due Date: Assign a deadline to the card. Overdue cards are often highlighted visually. Some Wekan views (like the Calendar View) rely on due dates.
• Start Date: You can optionally set a date when work on the card is planned to begin.
• End Date: Automatically records when the card was moved to the final list (e.g., "Done") or can be set manually.
• Custom Fields: (Intermediate/Advanced feature) Allows adding structured data fields defined at the board level (e.g., "Estimated Hours", "Priority Level (Dropdown)", "External Ticket ID").

Activities and Notifications

• Activity Feed: Each board (and often each card) has an activity feed showing a chronological history of actions: card creation, moves, comments, assignments, due date changes, etc. This provides transparency and traceability.
• Notifications: Wekan typically has a notification system (often represented by a bell icon in the header). You receive notifications for actions relevant to you, such as:
  • Being assigned to a card.
  • Being mentioned (@username) in a comment.
  • Comments on cards you are a member of.
  • Changes to cards you are watching/subscribed to.
  • Due date reminders. Notification preferences can usually be adjusted in your user settings.

User Profile and Settings

Accessible usually by clicking your username or avatar in the header, this area allows you to:

• Change your full name, username, email address (may require confirmation).
• Change your password.
• Set your avatar/profile picture.
• Configure notification preferences.
• Manage language settings.
• Access API tokens (for advanced integrations).

Workshop Creating Your First Project Board

Goal: Gain practical experience with the core Wekan UI by creating and populating a simple Kanban board for a common student scenario.

Scenario: You and a couple of friends are starting a group project to write a research paper. You'll use your newly installed Wekan instance to organize the initial tasks.

Steps:

1. Log In to Wekan: Access your Wekan instance using the URL and the admin user account created in the previous workshop.

2. Create a New Board:

   • On the main dashboard, find and click the button to create a new board (e.g., "+ Create New Board").
   • Give the board a meaningful title: Research Paper Project.
   • Ensure the board visibility is set to "Private" (usually the default). Click "Create".
   • You should now be inside the newly created, empty board.

3. Create Standard Kanban Lists:

   • Boards often start with a default list (like "Tasks"). You can rename it or delete it if needed (hover over the list title, find the menu/edit option).
   • Find the option to add a new list (often a button or text input area labeled "Add List..." on the right side of the existing lists).
   • Create the following lists, one by one:
     1. To Do
     2. In Progress
     3. Review
     4. Done
   • You can reorder the lists by clicking and dragging their title bars if needed.

4. Create Sample Cards:

   • Under the To Do list, find the "+ Add Card" option.
   • Create the following cards by typing the title and pressing Enter (or clicking "Add"):
     • Define Research Topic and Scope
     • Conduct Initial Literature Search
     • Develop Research Questions
     • Create Paper Outline
     • Write First Draft Introduction
   • You should now see these cards stacked vertically within the To Do list.

5. Add Details to a Card:

   • Click on the card Conduct Initial Literature Search to open its details view.
   • Assign Member: Click on "Members". Since you're the only user currently, assign yourself by clicking your username/avatar.
   • Add Description: Click in the "Description" area. Add some details, perhaps using Markdown:

     Find relevant academic papers and books on the chosen topic.
     
     **Goals:**
     *   Identify at least 10 key sources.
     *   Summarize main arguments of 3 core papers.
     *   Check library resources.
     
     Useful databases: [Link to University Library Search], [Link to Google Scholar]
     

     Click "Save" or click outside the description box.
   • Create Checklist: Click on "Add Checklist". Give it a title like Search Tasks. Add checklist items:
     • Search Uni Library Database
     • Search Google Scholar
     • Check Recommended Reading List
     • Compile Bibliography Click "Add" after each item. You can check off items later.
   • Set Due Date: Click on "Due Date". Select a date a week from now using the calendar picker. Click "Save". Notice the due date appears on the card.
   • Close the card details view by clicking the 'X' or outside the card modal.

6. Explore Adding Labels:

   • In the board view (not inside a card), look for the board menu (often three dots or a "Show Menu" link on the right).
   • Find the "Labels" section. Click "Create a new label".
   • Create a few labels with distinct colors:
     • Urgent (Red)
     • Research (Blue)
     • Writing (Green)
     • Needs Discussion (Yellow)
   • Close the menu. Now, open the Define Research Topic and Scope card. Click "Labels" and select the Urgent and Needs Discussion labels. Close the card details. You should see the color indicators on the card in the list view.

7. View Activity Feed:

   • Go back to the board menu ("Show Menu").
   • Click on "Activity".
   • Observe the log of actions you've performed: board creation, list creation, card creation, adding details, assigning labels, etc.

8. Simulate Progress:

   • Drag the card Define Research Topic and Scope from the To Do list to the In Progress list. Notice how intuitive the drag-and-drop interface is.

You have now successfully created a basic project board, added tasks with details, categorized them, and simulated workflow progress. This forms the foundation for using Wekan effectively.

3. User Management and Permissions

As projects grow and involve collaboration, managing users and controlling access becomes essential. Wekan provides tools for administrators to handle user accounts and define who can see and interact with different boards.

Admin Panel Overview

The Admin Panel is the central hub for managing your Wekan instance. Only users designated as administrators have access to it. Typically, you can access it via a link in the header bar (often your username dropdown) or a dedicated section if you are logged in as an admin.

Key areas within the Admin Panel usually include:

• User Management: Creating, editing, disabling, and deleting user accounts.
• Settings: Global settings for the Wekan instance (e.g., registration options, email settings, layout).
• Version Information: Shows the current Wekan version.
• Feature Flags/Permissions: Might allow enabling/disabling certain features globally.

The exact layout and options depend on the Wekan version. Explore the panel carefully when you first gain admin access.

Creating Modifying and Deleting Users

Within the Admin Panel's user management section:

• Creating Users: Usually involves providing a username, email address, and an initial password (which the user should change on first login). You might also assign roles during creation.
• Modifying Users: Allows admins to change user details (username, email - though email changes might require verification), reset passwords, activate/deactivate accounts, and change user roles.
• Deleting Users: Permanently removes a user account. Be cautious with this, as it might affect historical data (e.g., comments made by the user might show as 'unknown user'). Deactivating is often a safer alternative if you might need to reinstate the user later.

User Roles

Wekan typically has a few basic roles:

• Admin: Full control over the Wekan instance via the Admin Panel. Can manage all users, boards (even private ones they aren't members of), and global settings. The first registered user automatically gets this role. You can promote other users to Admin status. Use this role sparingly.
• Normal User (or Member): Can create boards, be invited to boards, and interact with cards based on board-level permissions. Cannot access the Admin Panel. This is the standard role for most users.
• Comment-Only User (potential role): Some configurations might allow roles with restricted permissions, like only being able to view and comment on cards they are assigned to or mentioned in.
• No-Login User (potential role): Sometimes used for specific integrations or view-only access types.

Check your Wekan version's documentation for the specific roles available and their capabilities.

Board Permissions

Access control in Wekan primarily happens at the board level:

• Private Boards:
  • Only explicitly invited members can see or access the board.
  • This is the most common setting for team projects or personal boards.
  • The board creator is initially the only member and acts as the board admin.
  • Board admins (different from instance admins) can invite/remove members and manage board settings.
• Public Boards:
  • Visible to anyone who can access the Wekan instance URL, even if they are not logged in (depending on global settings).
  • Registered users might be able to join freely or comment depending on settings.
  • Use with extreme caution, especially if your instance is publicly accessible on the internet. Generally suitable only for publicly shared information or templates.
• Team Boards (if feature exists):
  • Some Wekan versions or related forks might have a "Team" or "Organization" concept.
  • Boards can be assigned to a team, and all team members automatically get access based on predefined team roles (e.g., team members can view, team admins can manage). This simplifies managing access for stable groups.

Assigning Members to Boards and Cards

• Board Membership:
  • For private boards, the Board Admin (usually the creator initially, but others can be promoted) manages membership.
  • Go to the Board Menu -> Members -> Invite. You can typically search for existing users by username and add them.
  • You can assign roles within the board to members:
    • Admin: Can change board settings (rename, change background, manage labels), manage members, and has full access to all cards.
    • Normal Member: Can create/edit cards, move cards, comment, etc., but cannot change board settings or manage members.
    • Comment Only (or similar): Might only be able to view cards and add comments.
• Card Membership:
  • Assigning a user to a specific card (via the card details -> Members) indicates they are responsible for or involved with that task.
  • Assigned members often receive notifications about changes to that card.
  • Assigning members to cards does not grant them access to the board itself; they must already be board members.

Organization/Team Management

If your Wekan instance supports Organizations or Teams (check Admin Panel or documentation):

• Admins can create Teams/Organizations.
• Users can be added as members to these Teams.
• Boards can be associated with a Team, simplifying access control for groups. This avoids having to invite the same list of users to multiple related boards individually.

Workshop Managing a Team Project

Goal: Practice creating new users, managing board permissions, and assigning roles for a collaborative project.

Scenario: Continuing with the "Research Paper Project", you need to add your two group members (student_a, student_b) to Wekan and give them access to the project board.

Steps:

1. Access the Admin Panel:

   • Log in to Wekan as the admin user created earlier.
   • Find the link to the Admin Panel (often in the top-right user dropdown menu). Click it.

2. Create New User Accounts:

   • Navigate to the User Management section within the Admin Panel.
   • Find the option to "Add User" or "Create User".
   • Create the first student user:
     • Username: student_a
     • Email: student_a@example.com (use a real email if you want to test email features later, otherwise a fake one is fine)
     • Password: Set a temporary password (e.g., Password123!). Make a note of it.
     • Ensure the role is "Normal User" (not Admin).
     • Click "Create" or "Save".
   • Repeat the process to create the second student user:
     • Username: student_b
     • Email: student_b@example.com
     • Password: Set a temporary password.
     • Role: "Normal User".
     • Click "Create" or "Save".
   • You should now see student_a and student_b listed along with your admin account.

3. Navigate to the Project Board:

   • Exit the Admin Panel and return to the main Wekan dashboard (usually by clicking the Wekan logo or a "Boards" link).
   • Open the Research Paper Project board you created earlier.

4. Verify Board Privacy:

   • Open the Board Menu (e.g., "Show Menu").
   • Check the board's visibility settings. Ensure it is set to "Private". If not, change it to Private.

5. Invite Members to the Board:

   • In the Board Menu, go to the "Members" section.
   • You should see yourself listed as a Board Admin.
   • Find the "Invite" or "Add Member" option.
   • Search for student_a. Select the user when they appear.
   • Assign them the "Normal Member" role for this board. Click "Add" or "Invite".
   • Repeat the process to search for and add student_b as a "Normal Member".
   • You should now see all three users listed as members of the board.

6. Assign Cards to New Members:

   • Close the Board Menu.
   • Find the card Conduct Initial Literature Search in the To Do list (or In Progress if you moved it). Click to open its details.
   • Click on "Members". You should now see student_a and student_b available.
   • Click on student_a to assign them to this card. You can unassign yourself if needed. Close the card details.
   • Open the card Create Paper Outline. Click "Members" and assign student_b to this card. Close the card details.

7. Simulate Student Access (Optional but Recommended):

   • Open a different web browser (or an incognito/private window) to avoid logging out your admin session.
   • Navigate to your Wekan URL.
   • Log in as student_a using the username and temporary password you set.
   • Wekan might prompt student_a to change their password upon first login. Do so.
   • Observe what student_a can see. They should only see the Research Paper Project board on their dashboard.
   • Enter the board. student_a should be able to see all lists and cards.
   • student_a should be able to move the card they are assigned (Conduct Initial Literature Search) to the In Progress list.
   • student_a should not see the Admin Panel option. They should also not be able to access Board Settings (like changing the board title or managing members) if they have the "Normal Member" role.
   • Log out as student_a. (Optional: Repeat the login process for student_b to verify their access).

You have now successfully configured user accounts and managed board-level permissions, enabling collaboration within your self-hosted Wekan instance.

4. Advanced Board Configuration and Features

Beyond basic lists and cards, Wekan offers several features to refine your workflow, improve visualization, and manage tasks more effectively. Mastering these intermediate features can significantly enhance your productivity and project clarity.

Board Settings Deep Dive

Accessible via the Board Menu ("Show Menu"), the settings area allows board admins to customize the board's appearance and behavior:

• Backgrounds: Change the board background from a solid color to various built-in images or potentially upload custom images (depending on Wekan version and configuration). This can help visually distinguish between different project boards.
• Card Colors: Some versions allow setting card colors based on labels or other criteria, enhancing visual scanning.
• Swimlanes: A powerful feature for adding a horizontal dimension to your board. While lists represent workflow stages (vertical columns), swimlanes represent categories like team members, sub-projects, priority levels, or product lines (horizontal rows). Cards exist at the intersection of a list and a swimlane. This helps visualize workload distribution or manage parallel streams within a single board. You typically activate and define swimlanes in the board settings.
• Board Title/Description: Edit the name and add a description for the board.
• Permissions: (As covered before) Manage who can access the board (Public/Private).
• Labels: Create, edit, and delete the colored labels available for use on cards within this board.

Using Labels Effectively

Labels are simple but versatile. Best practices include:

• Consistency: Define a clear meaning for each label color/name across your boards (or at least within a team).
• Prioritization: Use labels like "Urgent", "High", "Medium", "Low".
• Categorization: "Bug", "Feature", "Question", "Documentation", "Meeting Action Item".
• Status: While lists handle main workflow status, labels can add nuance like "Blocked", "Needs Review", "Requires Feedback".
• Filtering: Labels are most powerful when combined with filtering (see below).

Don't overuse labels; too many can become visual clutter. Find a balance that provides clarity.

Implementing Checklists for Sub-tasks

As seen briefly before, checklists within a card are perfect for:

• Breaking down complex tasks into smaller, manageable steps.
• Defining "Definition of Done" criteria for a task.
• Tracking progress on multi-step items without creating numerous small cards. Each item can be checked off, providing a clear visual indicator (e.g., 3/5 Done) and a progress bar on the card.

Utilizing Due Dates and Calendar View

• Due Dates: Assigning due dates makes deadlines explicit. Wekan typically highlights overdue cards visually (e.g., red date indicator).
• Calendar View: Many Wekan versions offer a Calendar View (accessible from the board menu or header). This view displays cards on a calendar based on their Due Date (or sometimes Start/End dates). It provides an excellent overview of upcoming deadlines and helps in planning and identifying potential bottlenecks. Cards can often be dragged and dropped on the calendar to reschedule their due dates.

Filtering and Searching Cards Efficiently

As boards grow, finding specific cards becomes crucial. Wekan provides filtering capabilities (usually accessible via a "Filter" button or icon near the top of the board):

• Filter by Label: Show only cards with specific labels applied (e.g., show all "Urgent" cards).
• Filter by Member: Show only cards assigned to a specific user (e.g., see all tasks assigned to student_a).
• Filter by Due Date: Show cards due soon, overdue cards, or cards within a specific date range.
• Filter by Title/Description Text: Search for keywords within card titles or descriptions.
• Combine Filters: Most interfaces allow combining multiple filter criteria (e.g., show "Urgent" cards assigned to student_a).

Filtering is non-destructive; it just changes your current view of the board. Clear the filters to see all cards again.

Archiving and Restoring Cards Lists Boards

Instead of permanently deleting completed items, Wekan uses an archiving system:

• Archiving Cards: When a task is truly finished and you want to remove it from the active board view (e.g., from the "Done" list), you can archive it (option usually in the card details menu). Archived cards are hidden but not deleted.
• Archiving Lists: If a stage in your workflow becomes obsolete, you can archive the entire list. All cards within that list will also be archived.
• Archiving Boards: Completed projects can be archived. The board disappears from the main dashboard but can be retrieved later.
• Restoring: Archived items (cards, lists, boards) can typically be found and restored via the Board Menu -> Archived Items (or similar). This allows you to retrieve historical data or undo accidental archiving. Archiving is generally preferred over deleting for traceability.

Introduction to Custom Fields

A powerful feature for adding structured information beyond standard fields:

• Definition: Board Admins can define Custom Fields in the Board Settings.
• Types: Common types include:
  • Text: For short text entries.
  • Number: For numerical values (e.g., story points, cost, hours).
  • Date: For additional date tracking.
  • Dropdown List: Predefined options for consistent categorization (e.g., Priority: P1, P2, P3).
  • Checkbox: For boolean flags (e.g., "Approved", "Requires Spec").
• Usage: Once defined, Custom Fields appear in the card details view, allowing users to input data. This data might also be usable in filters or displayed on the card front (depending on the version).

Workshop Optimizing Project Workflow

Goal: Apply advanced board features like swimlanes, labels, custom fields, and filtering to enhance the tracking and visualization of the "Research Paper Project".

Scenario: The research paper project is underway, and the team wants a clearer view of who is working on what, task priorities, and estimated effort.

Steps:

1. Log In and Access Board: Log in as your admin user (or any user with Board Admin privileges for the project board) and open the Research Paper Project board.

2. Add Swimlanes by Member:

   • Open the Board Menu ("Show Menu").
   • Find and select "Swimlanes".
   • Enable/Activate Swimlanes if necessary.
   • Add swimlanes for each team member: Your admin username, student_a, student_b. You might also want a "General" or "Unassigned" swimlane.
   • Close the menu/settings. Your board should now have horizontal lanes.
   • Drag and drop the existing cards into the appropriate member's swimlane based on who is primarily responsible (or who you assigned them to earlier). For example:
     • Drag Conduct Initial Literature Search into student_a's swimlane (within the correct list, e.g., In Progress).
     • Drag Create Paper Outline into student_b's swimlane.
     • Drag other cards into your swimlane or a general lane.
   • Observe how this gives an immediate visual overview of workload distribution across the workflow stages.

3. Utilize Labels for Priority and Status:

   • If you haven't already, ensure you have labels like Urgent (Red), Needs Discussion (Yellow), Writing (Green) defined (Board Menu -> Labels).
   • Apply the Urgent label to the Write First Draft Introduction card.
   • Apply the Needs Discussion label to the Develop Research Questions card.
   • Apply the Writing label to the Write First Draft Introduction card.
   • Notice the color indicators on the cards for quick scanning.

4. Add a Custom Field for Effort Estimation:

   • Open the Board Menu -> Custom Fields.
   • Click "Add Custom Field".
   • Name: Estimated Hours
   • Type: Select "Number".
   • Check the box "Show field on front of card" (if available) for better visibility.
   • Click "Save" or "Create".
   • Now, open a few cards (e.g., Conduct Initial Literature Search, Create Paper Outline, Write First Draft Introduction).
   • You should see the new "Estimated Hours" field. Enter some estimated numerical values (e.g., 8, 4, 12).
   • Close the card details. If you enabled "Show on front", you might see the estimate directly on the card view.

5. Practice Filtering:

   • Find the "Filter" option for the board (usually near the top).
   • Filter by Member: Click Filter -> Members -> select student_a. Observe that only cards assigned to student_a (and potentially cards not assigned to anyone, depending on implementation) are shown. The swimlanes might also adjust or highlight.
   • Clear Filter: Find the option to clear the current filter.
   • Filter by Label: Click Filter -> Labels -> select Urgent. Only cards with the "Urgent" label should be visible.
   • Combine Filters: While the "Urgent" filter is active, Click Filter -> Members -> select student_b. If student_b has no urgent cards assigned, the board might appear empty. Clear filters. Now try filtering by Label Needs Discussion and Member student_b.
   • Filter by Custom Field (if supported): Check if the filter options include your Estimated Hours field (e.g., filter for cards with > 5 hours).
   • Experiment with different filter combinations to understand how they help focus your view. Remember to clear filters when done.

6. Explore Calendar View:

   • Ensure a few cards have Due Dates set (open cards -> Due Date). Set dates for Create Paper Outline and Write First Draft Introduction.
   • Find the "Calendar" view option (often in the Board Menu or as a toggle/button near the board title).
   • Observe how the cards with due dates appear on the calendar. Try dragging a card on the calendar to a different date and verify that its due date is updated when you go back to the board view.

7. Archive a Completed Card:

   • Assume the Define Research Topic and Scope card is fully completed. Drag it to the Done list.
   • Open the card details. Find the "Archive" option (often under an "Actions" or ellipses (...) menu). Click it.
   • The card should disappear from the Done list.
   • Restore the Card: Go to Board Menu -> Archived Items. Find the card Define Research Topic and Scope. Click "Restore" or "Send back to board".
   • Go back to the board view. The card should reappear in the Done list.

By using swimlanes, custom fields, effective labeling, filtering, and the calendar view, you can manage your projects with much greater clarity and control within Wekan.

5. Backup Restore and Updates

Operating a self-hosted service like Wekan means you are responsible for its maintenance, including safeguarding your data through backups and keeping the software up-to-date. This section covers these critical operational tasks.

Importance of Backups

Data loss can occur due to various reasons: hardware failure, software bugs, accidental deletion, security breaches, or catastrophic server issues. Without backups, recovering your project boards, user data, and task history can be impossible. Regular, automated, and tested backups are non-negotiable for any self-hosted application.

Key Data to Back Up:

For Wekan, the most critical data is the MongoDB database, which stores all board information, users, cards, comments, etc. Depending on configuration, file attachments might also need separate backup if stored on the filesystem instead of within the database (check Wekan documentation for your version/setup).

Backup Strategies for Snap Installations

Backing up Snap installations can sometimes be less straightforward due to the Snap's confinement.

• Identify Data Location: The Wekan snap bundles its own MongoDB. You need to determine where the Snap stores its data. This location can sometimes change between Snap versions or be within a versioned directory under /var/snap/wekan/. Use commands like snap connections wekan or inspect the Snap's service files to find hints, or consult the specific Wekan Snap documentation.
• Built-in Snap Commands (Ideal but not always available): Check if the Wekan snap provides specific commands for backup/restore (e.g., sudo wekan.backup or similar). Run snap info wekan or check available commands starting with wekan. by typing wekan. and pressing Tab (if command completion is set up). This is the cleanest method if available.
• Manual Database Backup (Using mongodump within the Snap): If no built-in command exists, you might need to execute mongodump against the MongoDB instance running inside the Snap.
  1. Find MongoDB Port/Socket: Determine how the Snap's MongoDB is listening (e.g., on a specific port like 27019 or a Unix socket). This might require inspecting Snap configuration (sudo snap get wekan -d) or service files.
  2. Execute mongodump: You might need to use snap run --shell wekan to get a shell within the Snap's environment or use sudo wekan.mongo (if a mongo client command is provided) or potentially install a compatible mongodb-database-tools package outside the snap and connect to the Snap's MongoDB port/socket.

     # Example assuming MongoDB listens on default port 27017 (adjust if different for Snap)
     # This might require installing mongodb-database-tools separately: sudo apt install mongodb-database-tools
     mongodump --uri="mongodb://<user>:<password>@<host>:<port>/wekan" --archive="wekan-backup-$(date +%Y%m%d_%H%M%S).gz" --gzip
     # Note: The Snap's MongoDB might not require authentication by default from localhost
     # Consult Snap docs for connection details. Port might be 27019. Database name is often 'wekan'.
     # Example might be: mongodump --port 27019 --db wekan --archive="wekan-backup.gz" --gzip
     

• Filesystem Backup (Less Ideal for DB): You could try backing up the data directory found in step 1 while Wekan/MongoDB is stopped (sudo snap stop wekan). However, directly copying live database files is risky and can lead to corrupted backups. Using mongodump is strongly preferred for database integrity.

Backup Strategies for Docker Installations

Docker volumes make data management clearer. The primary goal is to back up the MongoDB data volume (wekan-db-data in our example docker-compose.yml).

• Using docker exec with mongodump (Recommended): This runs the mongodump command inside the running MongoDB container, ensuring a consistent snapshot.
  1. Identify Container Name: Use docker compose ps to confirm the MongoDB container name (e.g., wekan-db).
  2. Run mongodump:

     # Create a backup directory on the host
     mkdir -p ~/wekan_backups
     
     # Execute mongodump inside the container, outputting to stdout, redirecting to a compressed file on the host
     docker exec wekan-db sh -c 'mongodump --archive --db=wekan --gzip' > ~/wekan_backups/wekan-db-backup-$(date +%Y%m%d_%H%M%S).gz
     
     # Explanation:
     #   docker exec wekan-db: Execute a command in the 'wekan-db' container.
     #   sh -c '...': Run the command within a shell inside the container.
     #   mongodump: The MongoDB backup tool (available in the official mongo image).
     #   --archive: Output data to a single archive file (useful for piping).
     #   --db=wekan: Specify the database name used in MONGO_URL (e.g., 'wekan').
     #   --gzip: Compress the output archive using gzip.
     #   > ~/wekan_backups/... .gz: Redirect the standard output (the archive data) to a file on the host machine.
     

• Backing Up the Docker Volume Directly (Less Recommended for DB): You could find the volume's location on the host (docker volume inspect wekan-db-data) and back up that directory. However, this requires stopping the MongoDB container (docker compose stop wekan-db) to ensure data consistency, leading to downtime. mongodump is generally better as it can often run on a live database.
• Backup Scripting: Automate the docker exec mongodump command using a simple bash script and schedule it using cron.

#!/bin/bash
BACKUP_DIR="/home/your_user/wekan_backups" # Use absolute path
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/wekan-db-backup-$TIMESTAMP.gz"
CONTAINER_NAME="wekan-db" # Match your container name
DB_NAME="wekan"         # Match your database name

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# Perform the backup
echo "Starting Wekan MongoDB backup..."
if docker exec "$CONTAINER_NAME" sh -c "mongodump --archive --db=$DB_NAME --gzip" > "$BACKUP_FILE"; then
    echo "Backup successful: $BACKUP_FILE"
else
    echo "ERROR: Backup failed!"
    rm -f "$BACKUP_FILE" # Remove potentially incomplete file
    exit 1
fi

# Optional: Prune old backups (e.g., keep last 7 days)
echo "Pruning old backups (older than 7 days)..."
find "$BACKUP_DIR" -name 'wekan-db-backup-*.gz' -mtime +7 -exec echo "Deleting {}" \; -exec rm {} \;

echo "Backup process finished."
exit 0

Save this script (e.g., wekan_backup.sh), make it executable (chmod +x wekan_backup.sh), and add it to your crontab (crontab -e) to run daily (e.g., 0 2 * * * /path/to/wekan_backup.sh >> /var/log/wekan_backup.log 2>&1).

• Storing Backups Securely: Store backups on a different physical device or cloud storage (e.g., S3, Backblaze B2). Encrypt sensitive backups. Regularly test your restore process!

Restore Procedures

Restoring involves using mongorestore to import the data from your backup file.

• Snap Restore:
  • If the Snap provided a restore command, use that.
  • Otherwise, you'll need to execute mongorestore within the Snap's context, pointing it to your backup file. This might involve stopping Wekan (sudo snap stop wekan), running mongorestore (similar complexity as mongodump), and restarting (sudo snap start wekan). Consult specific Snap documentation. --drop option in mongorestore is often needed to clear existing data before restoring.
• Docker Restore:
  1. Stop Wekan App: Stop the Wekan application container to prevent writes during restore: docker compose stop wekan-app. The database container (wekan-db) should remain running.
  2. Run mongorestore: Copy the backup file into the container or pipe it. Piping is often easier:

     # Example restoring from ~/wekan_backups/latest_backup.gz
     cat ~/wekan_backups/latest_backup.gz | docker exec -i wekan-db sh -c 'mongorestore --archive --db=wekan --drop --gzip'
     
     # Explanation:
     #   cat ... |: Outputs the backup file content to standard output.
     #   docker exec -i wekan-db: Executes a command in the container, '-i' keeps stdin open to receive the piped data.
     #   sh -c '...': Runs the command in a shell.
     #   mongorestore: The MongoDB restore tool.
     #   --archive: Expects data from a single archive file (from stdin in this case).
     #   --db=wekan: Specifies the target database.
     #   --drop: Drops collections from the database before restoring (ensures a clean restore). Use with caution if merging data.
     #   --gzip: Indicates the incoming data stream is gzipped.
     

  3. Restart Wekan App: Once mongorestore completes, restart the Wekan application container: docker compose start wekan-app.
  4. Verify: Check Wekan to ensure your boards and data are restored correctly. Check logs (docker compose logs wekan-app) for any errors.

Updating Wekan

Keeping Wekan updated provides access to new features, bug fixes, and crucial security patches.

• Updating the Snap Package:
  • Snaps can often auto-update, but you can trigger it manually.
  • Check for updates: sudo snap refresh --list
  • Update Wekan (if an update is available): sudo snap refresh wekan
  • Read Release Notes: Before updating, always check the Wekan release notes or Snap Store notes for any breaking changes or specific instructions.
• Updating the Docker Image:
  1. Read Release Notes: Check the Wekan GitHub releases page or Docker Hub page for the version you intend to update to. Note any changes in environment variables, dependencies, or update procedures.
  2. Pull the Latest Image: Fetch the newest version of the Wekan image specified in your docker-compose.yml.

     docker compose pull wekan
     # Or, if you specified a version tag like wekanteam/wekan:v7.38,
     # update the tag in docker-compose.yml first, then pull:
     # nano docker-compose.yml (change image tag)
     # docker compose pull wekan
     

  3. Stop and Recreate Containers: Apply the new image by stopping the current containers and recreating them using the updated image and configuration. The database container usually doesn't need recreating unless you're updating MongoDB itself. The named volume wekan-db-data persists the data.

     # This command stops, removes, and recreates the 'wekan' container
     # using the newly pulled image and current docker-compose.yml settings.
     # It leaves the 'wekan-db' container and its data volume untouched.
     docker compose up -d --no-deps wekan
     
     # Explanation:
     #  up -d: Ensure containers are running in detached mode.
     #  --no-deps: Only recreate the specified service ('wekan'), not its dependencies ('wekan-db').
     #  wekan: The service name to recreate.
     

     Alternatively, a full docker compose down && docker compose up -d will recreate both, but is usually unnecessary for just a Wekan app update and causes slightly more downtime.
  4. Verify: Access Wekan and check the Admin Panel or footer for the updated version number. Test basic functionality.

Before any update, ensure you have a recent, tested backup!

Workshop Simulating Backup and Restore

Goal: Gain hands-on experience with the Wekan backup and restore process using the Docker method.

Scenario: Perform a manual backup of your current Wekan state (Research Paper Project board, users). Then, simulate a data loss event by removing the database volume and restore Wekan from the backup.

Steps (Docker Example):

1. Ensure Wekan is Running: Make sure your Wekan containers are running: docker compose ps.

2. Create a Backup:

   • Create a backup directory on your host: mkdir -p ~/wekan_backups
   • Execute the mongodump command within the wekan-db container, saving the output to your host:

     docker exec wekan-db sh -c 'mongodump --archive --db=wekan --gzip' > ~/wekan_backups/wekan-manual-backup-$(date +%Y%m%d).gz
     

   • Verify the backup file exists: ls -lh ~/wekan_backups. Note its approximate size.

3. Simulate Data Loss (CAUTION: This deletes your current database data):

   • Stop and remove the containers and their associated volumes. The -v flag is critical here as it removes the named volumes defined in the docker-compose.yml file, including wekan-db-data.

     # Make sure you are in the directory with your docker-compose.yml file (~/wekan-docker)
     docker compose down -v
     

   • Verify removal: docker ps -a should show no wekan containers, and docker volume ls should not list wekan-docker_wekan-db-data (the name might have a prefix based on your directory).

4. Restart Wekan (Should be Empty):

   • Bring the containers back up. Docker Compose will recreate the named volumes, but they will be empty.

     docker compose up -d
     

   • Wait a minute for the containers to start. Access your Wekan URL (http://<your-server-ip>:3001).
   • You should be presented with the registration page again, as if it were a fresh installation. The database is empty. Do not register a new user yet.

5. Restore from Backup:

   • Stop the Wekan application container (leave the database running):

     docker compose stop wekan-app
     

   • Execute the mongorestore command, piping your backup file into the wekan-db container:

     # Replace 'wekan-manual-backup-YYYYMMDD.gz' with your actual backup filename
     cat ~/wekan_backups/wekan-manual-backup-*.gz | docker exec -i wekan-db sh -c 'mongorestore --archive --db=wekan --drop --gzip'
     

   • Wait for the command to complete. There might not be much output if successful.

6. Restart Wekan App and Verify:

   • Start the Wekan application container again:

     docker compose start wekan-app
     

   • Wait a few seconds, then refresh your Wekan page in the browser.
   • You should now see the login page (not the registration page).
   • Log in with your original admin user credentials.
   • Verify that your Research Paper Project board, lists, cards, users (student_a, student_b), swimlanes, labels, and custom fields are all restored.

This workshop demonstrates the critical importance and the practical steps of backing up and restoring your Wekan data. Remember to automate backups and test restores regularly.

6. Securing Your Wekan Instance

Running a web application accessible over a network requires careful attention to security. This section covers essential steps to harden your self-hosted Wekan installation, primarily focusing on enabling HTTPS and basic firewall configuration.

Importance of HTTPS

By default, you've likely accessed Wekan using http://, which transmits data (including usernames, passwords, and all your project information) in plain text. Anyone snooping on the network (e.g., on public Wi-Fi, or even your ISP) could potentially intercept this data.

HTTPS (HTTP Secure) encrypts the communication between the user's browser and your Wekan server using TLS/SSL certificates. This ensures:

• Confidentiality: Data cannot be easily read by eavesdroppers.
• Integrity: Data cannot be tampered with during transmission.
• Authentication: Provides some assurance that the user is connecting to the actual server associated with the domain name (preventing simple man-in-the-middle attacks).

Modern browsers also heavily favor HTTPS, marking HTTP sites as "Not Secure". Using HTTPS is essential for any production or publicly accessible Wekan instance.

Setting up a Reverse Proxy (Nginx Example)

Directly exposing the Wekan application server (whether run via Snap or Docker) to the internet is generally not recommended. A reverse proxy like Nginx or Apache sits in front of Wekan, receives incoming web requests, and forwards them to the Wekan application running on a local port (e.g., localhost:3001).

Benefits of using a reverse proxy:

• HTTPS/TLS Termination: The reverse proxy handles the complexities of SSL/TLS encryption and decryption. Wekan itself can continue running on plain HTTP locally, simplifying its configuration.
• Load Balancing: Can distribute traffic across multiple Wekan instances (advanced setup).
• Caching: Can cache static assets (like images, CSS, JS) to improve performance.
• Security Layer: Can implement security headers, rate limiting, and access controls.
• Serving Multiple Sites: Allows hosting multiple web applications on the same server using different domain names or paths, all managed by the reverse proxy on standard ports 80/443.

We'll use Nginx as an example.

1. Install Nginx

# On Ubuntu/Debian
sudo apt update
sudo apt install nginx
sudo systemctl start nginx
sudo systemctl enable nginx # Ensure it starts on boot

2. Basic Nginx Configuration for Wekan

Create a new Nginx configuration file for your Wekan site. Replace wekan.yourdomain.com with the actual domain name you intend to use.

sudo nano /etc/nginx/sites-available/wekan.yourdomain.com

Paste the following basic configuration, adjusting server_name and proxy_pass target based on your Wekan setup:

server {
    listen 80; # Listen on port 80 for initial HTTP requests
    listen [::]:80;

    server_name wekan.yourdomain.com; # Replace with your domain/subdomain

    # Optional: Increase max upload size if needed for large attachments
    client_max_body_size 100M;

    location / {
        # Forward requests to the Wekan instance
        # If Wekan (Docker/Snap) is listening on port 3001 on the same machine:
        proxy_pass http://127.0.0.1:3001;

        # --- Important Proxy Headers ---
        # Pass the original Host header to Wekan
        proxy_set_header Host $host;
        # Pass the original client's IP address
        proxy_set_header X-Real-IP $remote_addr;
        # Identify the proxy server and pass the client's IP via X-Forwarded-For
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Indicate the original protocol (http or https) - crucial for redirects and ROOT_URL
        proxy_set_header X-Forwarded-Proto $scheme;
        # Pass the Forwarded header (newer standard)
        proxy_set_header Forwarded $proxy_add_forwarded;

        # --- WebSocket Support (Required for Wekan's real-time features) ---
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # Optional: Increase proxy timeouts if experiencing issues
        # proxy_connect_timeout 60s;
        # proxy_send_timeout    60s;
        # proxy_read_timeout    60s;
    }

    # Optional: Access and error logs for this site
    access_log /var/log/nginx/wekan.yourdomain.com.access.log;
    error_log /var/log/nginx/wekan.yourdomain.com.error.log;
}

Explanation:

• listen 80;: Nginx listens for incoming HTTP requests on port 80.
• server_name ...;: Specifies which domain this configuration applies to.
• client_max_body_size ...;: Sets the maximum allowed size for file uploads via Nginx. Adjust as needed.
• location / { ... }: Applies the contained directives to all requests for this server name.
• proxy_pass http://127.0.0.1:3001;: Crucial! This tells Nginx to forward incoming requests to your Wekan application, which is assumed to be listening on port 3001 on the same machine (127.0.0.1). Adjust the port if your Wekan (Snap or Docker) is listening on a different port.
• proxy_set_header ...: These headers pass important information from the original client request and the proxy itself to the backend Wekan application. Wekan uses headers like X-Forwarded-Proto and Host (combined with its ROOT_URL setting) to generate correct URLs and handle redirects properly, especially once HTTPS is enabled.
• WebSocket Headers (Upgrade,Connection`): These are essential for Wekan's real-time features (like seeing card movements instantly without refreshing).

3. Enable the Site and Test Nginx Configuration

# Create a symbolic link from sites-available to sites-enabled
sudo ln -s /etc/nginx/sites-available/wekan.yourdomain.com /etc/nginx/sites-enabled/

# Test the Nginx configuration for syntax errors
sudo nginx -t

# If syntax is ok, reload Nginx to apply the changes
sudo systemctl reload nginx

4. Configure Wekan's ROOT_URL

Now that Nginx is handling requests on port 80 for wekan.yourdomain.com, you must update Wekan's ROOT_URL environment variable to match the URL users will now use (without the internal port number).

• For Docker: Edit your docker-compose.yml file:

  environment:
    - MONGO_URL=mongodb://wekan-db:27017/wekan
    - ROOT_URL=http://wekan.yourdomain.com # Changed! No port 3001 here.
    # ... other variables
  

  Then apply the change: docker compose up -d --no-deps wekan
• For Snap: Update the snap setting:

  sudo snap set wekan root-url='http://wekan.yourdomain.com' # Changed! No port 3001 here.
  sudo systemctl restart snap.wekan.wekan
  

At this point, if your DNS is configured correctly (pointing wekan.yourdomain.com to your server's public IP address), you should be able to access Wekan via http://wekan.yourdomain.com. Nginx listens on port 80 and forwards the traffic internally to Wekan on port 3001 (or whichever port you configured).

Enabling HTTPS with Let's Encrypt

Let's Encrypt is a free, automated, and open Certificate Authority (CA) that provides TLS/SSL certificates. Certbot is a client tool that simplifies obtaining and renewing these certificates.

1. Install Certbot and Nginx Plugin

# On Ubuntu/Debian
sudo apt update
sudo apt install certbot python3-certbot-nginx

2. Obtain and Install Certificate

Run Certbot, telling it to use the Nginx plugin and specifying the domain name from your Nginx configuration.

# Replace wekan.yourdomain.com with your actual domain
sudo certbot --nginx -d wekan.yourdomain.com

Certbot will:

• Communicate with Let's Encrypt to verify you control the domain.
• Ask for an email address (for renewal reminders and urgent notices).
• Ask you to agree to the Terms of Service.
• Ask if you want to share your email with the EFF (optional).
• Crucially: It will detect your Nginx configuration for that domain and ask if you want it to automatically modify the configuration to enable HTTPS (including setting up redirects from HTTP to HTTPS). Choose the option to redirect (usually option 2).

If successful, Certbot will modify your Nginx configuration file (/etc/nginx/sites-available/wekan.yourdomain.com) to include SSL settings, certificate paths, and the HTTP-to-HTTPS redirect. It will also automatically reload Nginx.

Your Nginx configuration will now look something like this (simplified):

server {
    server_name wekan.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        # ... proxy headers ...
    }

    listen [::]:443 ssl ipv6only=on; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/wekan.yourdomain.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/wekan.yourdomain.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

server {
    if ($host = wekan.yourdomain.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80;
    listen [::]:80;
    server_name wekan.yourdomain.com;
    return 404; # managed by Certbot
}

3. Configure Automatic Renewal

Let's Encrypt certificates are valid for 90 days. The Certbot package usually installs a systemd timer or cron job to automatically check for and renew certificates nearing expiration. You can test the renewal process (without actually renewing unless needed):

sudo certbot renew --dry-run

4. Update Wekan's ROOT_URL (Again!) for HTTPS

Since access is now enforced over HTTPS, you must update Wekan's ROOT_URL one last time to use https://.

• For Docker: Edit docker-compose.yml:

  environment:
    - MONGO_URL=mongodb://wekan-db:27017/wekan
    - ROOT_URL=https://wekan.yourdomain.com # Changed to HTTPS!
    # ... other variables
  

  Apply: docker compose up -d --no-deps wekan
• For Snap: Update the snap setting:

  sudo snap set wekan root-url='https://wekan.yourdomain.com' # Changed to HTTPS!
  sudo systemctl restart snap.wekan.wekan
  

Now, access https://wekan.yourdomain.com. Your browser should show a lock icon, indicating a secure connection. Any attempt to access the http:// version should automatically redirect to https://.

Wekan Environment Variables for Security

Besides ROOT_URL, other environment variables impact security:

• ROOT_URL: As demonstrated, absolutely critical for correct operation behind a reverse proxy and with HTTPS.
• MAIL_URL: Needed for password resets, email verification, and board invitations via email. Requires configuring SMTP details (see Advanced Customization). Without it, password recovery is impossible if a user forgets theirs. Format: smtp://user:password@host:port.
• REGISTER_DISABLED=true: Set this environment variable (in docker-compose.yml or via snap set wekan register-disabled=true) after the initial admin user is created to prevent random visitors from creating accounts on your instance. Users would then need to be created manually by an admin.
• WITH_API=true: Enables the Wekan REST API (needed for integrations).
• BROWSER_POLICY_ENABLED=true: Enables stricter Content Security Policy (CSP) and related browser security headers, reducing risks like cross-site scripting (XSS). This is generally recommended but might occasionally interfere with certain complex setups or integrations if not configured correctly.

Consult the Wekan documentation for a full list of environment variables and their functions.

Firewall Configuration (UFW Example)

A firewall limits which network ports are accessible on your server. You should only allow traffic on ports you explicitly need. ufw (Uncomplicated Firewall) is a user-friendly frontend for iptables on Ubuntu/Debian.

1. Install UFW (if needed):

   sudo apt update
   sudo apt install ufw
   

2. Set Default Policies: Deny all incoming traffic by default, allow all outgoing.

   sudo ufw default deny incoming
   sudo ufw default allow outgoing
   

3. Allow Necessary Ports:
   • SSH (Essential for remote access): sudo ufw allow ssh (or sudo ufw allow 22/tcp if SSH runs on a non-standard port). Do this first to avoid locking yourself out!
   • HTTP (Port 80): Needed for initial Let's Encrypt validation and HTTP-to-HTTPS redirects. sudo ufw allow http (or sudo ufw allow 80/tcp).
   • HTTPS (Port 443): Needed for secure web traffic via Nginx. sudo ufw allow https (or sudo ufw allow 443/tcp).
   • Other Ports? Do NOT allow direct access to Wekan's internal port (e.g., 3001) or the MongoDB port (27017) from the outside world. Nginx handles external access on 80/443.
   • You can also allow Nginx profiles which combine common ports: sudo ufw allow 'Nginx Full' (allows both 80 and 443).
4. Enable UFW:

   sudo ufw enable
   # It will warn that this may disrupt existing connections. Type 'y' and press Enter.
   

5. Check Status:

   sudo ufw status verbose
   

   This should show rules allowing traffic on ports 22, 80, and 443, with the default policy denying other incoming traffic.

Workshop Securing Wekan with Nginx and Let's Encrypt

Goal: Configure secure HTTPS access for your Wekan instance using Nginx as a reverse proxy and obtain a free SSL certificate from Let's Encrypt.

Scenario: You have Wekan running (via Docker or Snap) accessible via http://<your-server-ip>:<port>. You have registered a domain name (e.g., wekan.yourdomain.com) and pointed its DNS A record to your server's public IP address. You want users to access it securely via https://wekan.yourdomain.com.

Prerequisites:

• A running Wekan instance (Docker or Snap). Note the internal IP and port it's listening on (e.g., 127.0.0.1:3001).
• A server with a public IP address.
• A registered domain name (or subdomain) pointing to the server's public IP address via DNS A record. Allow time for DNS propagation.
• sudo access on the server.

Steps:

1. Install Nginx:

   sudo apt update && sudo apt install nginx
   sudo systemctl enable --now nginx
   

2. Configure Nginx Reverse Proxy:

   • Create the Nginx config file: sudo nano /etc/nginx/sites-available/wekan.yourdomain.com (replace with your domain).
   • Paste the Nginx configuration provided earlier, ensuring:
     • server_name matches your domain exactly.
     • proxy_pass points to the correct internal IP and port where Wekan is listening (e.g., http://127.0.0.1:3001).
   • Enable the site: sudo ln -s /etc/nginx/sites-available/wekan.yourdomain.com /etc/nginx/sites-enabled/
   • Test Nginx config: sudo nginx -t
   • Reload Nginx: sudo systemctl reload nginx

3. Update Wekan ROOT_URL (HTTP):

   • Modify your Wekan configuration (Docker docker-compose.yml or sudo snap set wekan root-url) to use the HTTP version of your domain: ROOT_URL=http://wekan.yourdomain.com.
   • Restart Wekan (docker compose up -d --no-deps wekan or sudo systemctl restart snap.wekan.wekan).
   • Verify you can access Wekan via http://wekan.yourdomain.com (without the port).

4. Install Certbot:

   sudo apt install certbot python3-certbot-nginx
   

5. Obtain Let's Encrypt Certificate:

   sudo certbot --nginx -d wekan.yourdomain.com # Replace with your domain
   

   • Follow the prompts: enter email, agree to ToS, choose whether to share email.
   • Select the option to automatically redirect HTTP to HTTPS.
   • Certbot should confirm success and show certificate paths.

6. Configure Firewall (UFW):

   • Allow SSH: sudo ufw allow ssh
   • Allow Nginx HTTP/HTTPS: sudo ufw allow 'Nginx Full'
   • Enable UFW: sudo ufw enable (confirm with 'y')
   • Check status: sudo ufw status (should show ports 22, 80, 443 allowed).

7. Update Wekan ROOT_URL (HTTPS):

   • Modify your Wekan configuration again (Docker docker-compose.yml or sudo snap set wekan root-url) to use the HTTPS version of your domain: ROOT_URL=https://wekan.yourdomain.com.
   • Restart Wekan (docker compose up -d --no-deps wekan or sudo systemctl restart snap.wekan.wekan).

8. Final Verification:

   • Open your browser and navigate to https://wekan.yourdomain.com.
   • Verify the connection is secure (lock icon).
   • Try navigating to http://wekan.yourdomain.com – it should automatically redirect to the https:// version.
   • Log in and test basic Wekan functionality (e.g., moving cards) to ensure WebSockets are working correctly through the proxy.

You have now successfully secured your Wekan instance with Nginx and Let's Encrypt, providing encrypted communication and a professional setup.

7. Advanced Customization and Integration

Beyond the core features and security, Wekan offers possibilities for integration with other systems, automation, and further tailoring to specific needs.

Using Wekan API

Wekan provides a RESTful API (Application Programming Interface) that allows external applications and scripts to interact with Wekan data programmatically. To use the API:

• Enable API: Ensure the WITH_API=true environment variable is set (often default, but verify).
• Authentication: API access typically requires authentication using user-specific API tokens. Users can usually generate these tokens in their profile settings.
• Functionality: The API allows actions such as:
  • Listing boards, lists, cards.
  • Creating, modifying, deleting cards.
  • Adding comments, assigning members, managing labels via API calls.
  • Retrieving user information.
• Documentation: Refer to the official Wekan API documentation (often linked from the main Wekan repository or website) for detailed endpoints, request/response formats, and examples.
• Use Cases: Automating card creation from external systems (e.g., bug trackers, monitoring alerts), generating custom reports, integrating Wekan data into dashboards.

Webhooks for Automation

Webhooks allow Wekan to send notifications to external systems when specific events occur.

• Configuration: Typically configured within board settings. You define a target URL (an endpoint on another application or service that can receive HTTP POST requests).
• Events: You can often select which events trigger the webhook (e.g., card created, card moved, comment added, member assigned).
• Payload: When an event occurs, Wekan sends a JSON payload containing information about the event and the related object (card, list, board) to the specified URL.
• Use Cases:
  • Notifying a chat application (like Slack or Mattermost) when a card moves to "Done".
  • Triggering a CI/CD pipeline when a feature card moves to "Ready for Testing".
  • Updating an external time-tracking system when a card is moved into "In Progress".
  • Requires setting up an external service to listen for and process these webhook requests.

Custom Fields Deep Dive

We introduced Custom Fields earlier. Their power lies in adding structured data relevant to your specific workflow:

• Types Revisited: Explore all available types (Text, Number, Date, Dropdown, Checkbox, potentially others depending on version).
• Board-Specific: Remember custom fields are defined per board.
• Use Cases:
  • Software Dev: Story Points (Number), Priority (Dropdown: P0, P1, P2), Sprint (Dropdown), QA Tester (Dropdown).
  • Client Work: Client Name (Text), Billable Hours (Number), Approval Status (Checkbox or Dropdown).
  • Content: Target Publication Date (Date), Content Pillar (Dropdown), SEO Keywords (Text).
• Visibility: Configure if the field should show on the card front for quick visibility.
• Potential for Reporting: While Wekan's built-in reporting might be limited, data in custom fields can be extracted via the API for more sophisticated external reporting.

Board Templates

Creating boards with the same structure (lists, labels, custom fields) repeatedly can be tedious. Board Templates solve this:

• Creating a Template: Configure a board exactly as you want your template (with standard lists, labels, potentially template cards with common checklists). Then, use the Board Menu option "Make this board a template".
• Using a Template: When creating a new board, you'll have an option to "Create from template". Select your saved template, and the new board will inherit its structure.
• Use Cases: Standardizing project kickoffs, onboarding processes, recurring workflows (e.g., weekly meeting agendas).

Authentication Methods

While the default is username/password stored in Wekan's database, advanced configurations support integrating with external identity providers:

• LDAP/Active Directory: Allows users to log in using their existing corporate directory credentials. Requires configuring connection details (server, base DN, bind user, filters) via environment variables.
• OAuth2 (Google, GitHub, GitLab, etc.): Enables "Login with Google" or similar buttons. Requires registering Wekan as an OAuth application with the provider and configuring client ID, secret, and callback URL via environment variables.
• SAML: Another standard for enterprise single sign-on (SSO). Requires configuration exchange with the SAML Identity Provider (IdP).
• Configuration: Setting up these methods involves specific environment variables (e.g., LDAP_ENABLE=true, OAUTH2_GOOGLE_CLIENT_ID=...). Consult the Wekan documentation specific to the authentication method you want to implement. This significantly enhances user convenience and centralizes identity management.

Theming/Branding

Options for changing Wekan's visual appearance (beyond board backgrounds) are often limited in standard releases but might be possible:

• Custom CSS: Some setups might allow injecting custom CSS for minor tweaks.
• Forks/Source Builds: More extensive theming might require modifying the source code and creating a custom build.
• Check Documentation: Look for any official guidance on theming or branding possibilities for your specific Wekan version.

Workshop Setting up Email Notifications

Goal: Configure Wekan to send email notifications for password resets, invitations, and mentions.

Scenario: You want users (student_a, student_b) to be able to reset their own passwords if forgotten and receive email notifications when mentioned or added to boards. This requires configuring Wekan to use an external SMTP service.

Prerequisites:

• A running Wekan instance (Docker recommended for easy environment variable changes).
• Access to an SMTP server. Options include:
  • Transactional Email Service (Recommended): Services like SendGrid, Mailgun, Postmark, AWS SES offer free tiers suitable for low-volume use. Sign up and obtain SMTP credentials (server address, port (usually 587 for TLS), username, password/API key).
  • Existing Email Provider (e.g., Gmail): Possible but not recommended for applications due to security limitations (may require "less secure app access" or app-specific passwords, subject to rate limits). Check provider's documentation for SMTP details.
  • Self-Hosted SMTP Relay: If you run your own mail server or relay.

Steps:

1. Obtain SMTP Credentials:

   • Choose an SMTP provider (e.g., sign up for SendGrid's free plan).
   • Navigate their dashboard to find SMTP settings or create an API key that can be used as the SMTP password.
   • Note down:
     • SMTP Server Address (e.g., smtp.sendgrid.net)
     • SMTP Port (e.g., 587 or 465)
     • SMTP Username (e.g., apikey for SendGrid, or your full email address for others)
     • SMTP Password (the API key you generated or your email password)

2. Construct the MAIL_URL:

   • The format is smtp://username:password@hostname:port.
   • URL-encode any special characters in your username or password if necessary (though often not needed if using API keys).
   • Example (SendGrid using API key as password): smtp://apikey:<Your_SendGrid_API_Key>@smtp.sendgrid.net:587
   • Example (Generic): smtp://myuser%40example.com:MyP@sswOrd!@mail.example.com:587 (Note: @ in username needs encoding %40, some special chars might need it too).

3. Configure Wekan Environment Variable:

   • For Docker:
     1. Edit your docker-compose.yml file.
     2. Add or uncomment the MAIL_URL under the wekan: service's environment: section.

        services:
          wekan:
            # ... other settings ...
            environment:
              - MONGO_URL=mongodb://wekan-db:27017/wekan
              - ROOT_URL=https://wekan.yourdomain.com
              - MAIL_URL=smtp://apikey:<Your_SendGrid_API_Key>@smtp.sendgrid.net:587 # Add your actual URL here
              # Optional: Set the From address (defaults to user's email sometimes)
              # - MAIL_FROM=Wekan Notifications <noreply@wekan.yourdomain.com>
            # ... other settings ...
        

     3. Save the file.
     4. Apply the changes by restarting the Wekan container: docker compose up -d --no-deps wekan
   • For Snap:
     1. Use the snap set command. The exact key might vary (check snap info wekan or docs), but it's likely mail-url.

        # Enclose the URL in single quotes
        sudo snap set wekan mail-url='smtp://apikey:<Your_SendGrid_API_Key>@smtp.sendgrid.net:587'
        # Potentially set MAIL_FROM as well if supported
        # sudo snap set wekan mail-from='Wekan Notifications <noreply@wekan.yourdomain.com>'
        

     2. Restart Wekan services: sudo systemctl restart snap.wekan.wekan

4. Test Email Functionality:

   • Password Reset: Log out of Wekan. On the login page, click the "Forgot Password?" link. Enter the email address of one of your registered users (e.g., student_a@example.com). Click the reset button. Check that user's inbox (or the mail service's activity log) for a password reset email from Wekan. Follow the link to reset the password.
   • Invitation (requires valid email addresses for users): Log in as admin. Go to Admin Panel -> Users. Edit student_b. Ensure they have a real, accessible email address configured. Go to the Research Paper Project board -> Board Menu -> Members. If possible, remove and re-invite student_b using their email address. Check student_b's inbox for an invitation email.
   • Mention: Log in as student_a. Go to a card on the project board and add a comment mentioning the admin user (e.g., @admin_username Check this out!). Log in as the admin user and check your email (or notification settings) to see if you received an email notification about the mention.

5. Troubleshooting:

   • If emails are not sent, check Wekan logs (docker compose logs wekan-app or Snap logs) for SMTP connection errors (authentication failure, connection refused, timeouts).
   • Double-check your MAIL_URL for typos, correct port, and correct credentials.
   • Ensure your server's firewall (UFW) allows outgoing connections on the SMTP port (usually covered by ufw default allow outgoing).
   • Check your SMTP provider's dashboard for logs or errors. Ensure your account/domain is verified for sending if required.

Successfully configuring email significantly improves the usability and administration of your Wekan instance.

Workshop Creating a Board Template

Goal: Create a reusable template for future university group projects based on the structure you've established.

Scenario: You anticipate managing several similar group projects and want to quickly create new boards with the standard lists, labels, and maybe some initial template tasks.

Steps:

1. Prepare the Template Board:

   • Log in to Wekan and open the Research Paper Project board.
   • Review its structure. Ensure it has the lists you want as standard (e.g., To Do, In Progress, Review, Done).
   • Ensure it has the standard labels you want to reuse (e.g., Urgent, Needs Discussion, Research, Writing). Access via Board Menu -> Labels.
   • Ensure any standard Custom Fields you want in the template are defined (e.g., Estimated Hours). Access via Board Menu -> Custom Fields.
   • (Optional) Add some generic "template" cards to the To Do list that represent common starting tasks, perhaps with checklists:
     • Create a card named [Template] Define Project Scope. Add a checklist: "Agree on topic", "Define deliverables", "Set initial deadlines".
     • Create a card named [Template] Initial Setup. Add a checklist: "Create shared folder", "Schedule first meeting".
   • Remove any project-specific or completed cards if you don't want them in the template. Clean up the board so it represents a good starting point.

2. Create the Template:

   • Open the Board Menu ("Show Menu").
   • Find the "Templates" or "Board Templates" section. Alternatively, some versions might have the template option directly in the main board settings/menu.
   • Look for an option like "Convert board to template" or "Make this board a template". Click it.
   • You might be prompted to give the template a name, e.g., University Group Project Template.
   • Confirm the action. The board itself might now be marked as a template, or a template copy might be created.

3. Verify Template Creation:

   • Navigate back to your main Wekan Dashboard.
   • Look for a "Templates" section or tab. Your University Group Project Template should be listed there.

4. Create a New Board from the Template:

   • From the Dashboard, click the "+ Create New Board" button.
   • Look for an option like "Create from template?" or a dropdown menu listing available templates.
   • Select your University Group Project Template.
   • Give the new board a unique name, e.g., New Coursework Project Q4.
   • Click "Create".

5. Inspect the New Board:

   • Open the newly created New Coursework Project Q4 board.
   • Verify that it has the same lists (To Do, In Progress, etc.) as your template board.
   • Check if the labels (Urgent, Research, etc.) are available (Board Menu -> Labels).
   • Check if the custom fields (Estimated Hours) are present (Board Menu -> Custom Fields or open a card).
   • Check if the [Template] cards you created are present in the To Do list.
   • This new board is independent of the template; changes here won't affect the template, and vice-versa.

Using templates saves significant setup time and promotes consistency across similar projects managed within your Wekan instance.

Conclusion

Congratulations on working through this guide to self-hosting Wekan! You've journeyed from the initial setup and basic usage to advanced configuration, security hardening, and operational best practices.

Recap of Skills Learned

• Installation: You learned how to install Wekan using both Snap and Docker, understanding the pros and cons of each method.
• Core Usage: You mastered navigating the Wekan interface, utilizing Boards, Lists, and Cards effectively, and enriching tasks with details like checklists, labels, and due dates.
• User Management: You practiced creating users, managing permissions at the board level, and understanding user roles within Wekan.
• Advanced Features: You explored swimlanes, custom fields, filtering, the calendar view, and archiving to optimize project workflows.
• Operations: You learned the critical importance of backups, practiced backup and restore procedures (especially for Docker), and understood how to update your Wekan instance.
• Security: You implemented essential security measures by setting up Nginx as a reverse proxy, enabling HTTPS with Let's Encrypt, and configuring basic firewall rules.
• Customization & Integration: You gained insight into email notifications, board templates, and the potential of the Wekan API and webhooks for further automation and integration.

Benefits of Self-Hosting Wekan Revisited

By self-hosting, you've gained:

• Full Control: Your data resides on your infrastructure.
• Enhanced Privacy: You are not reliant on third-party privacy policies for your core project data.
• Cost Savings: No recurring software subscription fees.
• Customizability: Control over updates, authentication, and potential integrations.
• Invaluable Experience: Practical skills in Linux administration, Docker, Nginx, databases, security, and application management.

Further Exploration

Your Wekan journey doesn't have to end here:

• Explore the API: Dive into the Wekan API documentation and try scripting simple interactions.
• Experiment with Webhooks: Set up a simple listener service (e.g., using Node.js, Python Flask, or a service like n8n.io or Node-RED) to react to Wekan events.
• Try Different Authentication: If applicable, experiment with setting up LDAP or OAuth2 integration.
• Contribute: Wekan is open-source! Explore the code on GitHub, report bugs, suggest features, or even contribute code or documentation improvements.
• Alternative Setups: Explore running Wekan in Kubernetes or other container orchestration platforms if you're interested in larger-scale deployments.

Troubleshooting Tips and Resources

When things go wrong (and they sometimes do in self-hosting):

• Check Logs: This is usually the first step.
  • Docker: docker compose logs wekan-app and docker compose logs wekan-db.
  • Snap: Use journalctl to view logs related to the snap service: journalctl -u snap.wekan.wekan or look for log files within /var/snap/wekan/common/ or similar.
  • Nginx: Check Nginx error logs: /var/log/nginx/error.log and site-specific logs like /var/log/nginx/wekan.yourdomain.com.error.log.
• Consult Documentation: Revisit the official Wekan documentation on GitHub (github.com/wekan/wekan) and potentially the documentation for the specific installation method (Snap Store page, Docker Hub page).
• Search GitHub Issues: Check if others have encountered similar problems by searching the Wekan GitHub Issues tracker.
• Community Forums/Support: Look for community forums, mailing lists, or chat channels related to Wekan where you can ask for help. Provide details about your setup (OS, Wekan version, installation method, logs, what you've tried).
• Restart Services: Sometimes a simple restart can resolve temporary glitches (docker compose restart wekan-app or sudo systemctl restart snap.wekan.wekan).
• Check Reverse Proxy Config: If experiencing connection issues, double-check your Nginx configuration (sudo nginx -t) and ensure the proxy_pass target and ROOT_URL are correct.
• Browser Developer Tools: Use your browser's developer tools (F12) to check the Console for JavaScript errors and the Network tab for failed requests, which can provide clues.

Self-hosting is a rewarding endeavor that puts you in control. Keep experimenting, learning, and applying best practices, and your self-hosted Wekan instance will serve as a powerful tool for managing your tasks and projects.