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

Task/Project Management Kanboard

Introduction

Welcome to the comprehensive guide on self-hosting Kanboard, a free and open-source Kanban project management software. In today's world, efficient task and project management is crucial for individuals and teams alike, whether for academic projects, personal goals, or professional endeavors. While numerous cloud-based solutions exist, self-hosting offers significant advantages: complete data control, enhanced privacy, customization potential, and often, cost savings in the long run.

Kanboard stands out due to its simplicity, minimalism, and focus on the core Kanban methodology. It's lightweight, requires minimal dependencies, and can run on modest hardware, making it an excellent choice for self-hosting beginners and experienced users alike. Its philosophy is "less is more," providing essential features without overwhelming bloat.

This guide is designed for university students and anyone eager to learn the ins and outs of deploying and managing their own Kanboard instance. We will progress from the fundamentals of setting up Kanboard to advanced configurations, customization, and maintenance. Each section builds upon the previous one, offering theoretical knowledge followed by practical, hands-on workshops. These workshops use real-world scenarios to solidify your understanding and provide tangible skills you can apply immediately.

We assume you have a basic understanding of server concepts (like what a web server or database is) and are comfortable using a command-line interface (CLI), particularly on Linux-based systems, which are common for self-hosting. However, we will strive to explain concepts clearly and provide detailed steps.

By the end of this guide, you will not only have a fully functional, self-hosted Kanboard instance but also possess the knowledge to manage, customize, secure, and troubleshoot it effectively, empowering you to take full control of your project management workflow.

Let's embark on this journey to master self-hosted Kanboard!

1. Getting Started with Kanboard Self-Hosting

This initial section covers the essential groundwork needed to get Kanboard up and running. We'll discuss the necessary components, different ways to install Kanboard, and guide you through a basic manual installation process. Understanding these fundamentals is crucial before moving on to using and customizing Kanboard.

Prerequisites Deep Dive

Before you can install Kanboard, you need a suitable environment. Let's break down the components in detail:

• Server: This is the computer where Kanboard will live. It needs to be running continuously to be accessible.

  • Options:
    • Virtual Private Server (VPS): Services like DigitalOcean, Linode, Vultr, Hetzner Cloud offer virtual servers in the cloud. This is a popular choice for self-hosting as it provides a public IP address and reliable infrastructure. Costs vary depending on resources (CPU, RAM, storage).
    • Dedicated Server: Renting a physical server from a provider. More powerful and expensive than a VPS, typically overkill for just Kanboard unless you have other demanding applications.
    • Home Server: A computer (even a Raspberry Pi or an old laptop) running at your home. Requires configuring your home network (port forwarding) to be accessible from the internet, and you need a reliable internet connection. Dynamic DNS might be necessary if your home IP address changes.
    • Virtual Machine (VM): Software like VirtualBox or VMware allows you to run a separate operating system (e.g., Linux) within your primary OS (Windows, macOS). Useful for testing or local development but not ideal for a production service accessible to others unless configured correctly.
  • Minimum Requirements: Kanboard itself is very lightweight. A server with 1 vCPU, 512MB-1GB RAM, and a few GBs of storage is often sufficient for personal or small team use. Resource needs increase with user count, project complexity, and plugin usage.

• Operating System (OS): Kanboard is primarily developed and tested on Linux. While it might run on Windows or macOS with specific configurations (like XAMPP/MAMP), a Linux server environment is highly recommended for stability, security, and community support.

  • Recommended Linux Distributions: Debian, Ubuntu Server, CentOS/Rocky Linux/AlmaLinux are excellent choices due to their stability and extensive documentation. We will primarily use examples based on Debian/Ubuntu.

• Web Server: Software that listens for incoming HTTP(S) requests from browsers and serves web pages or forwards requests to application backends.

  • Popular Choices:
    • Apache (httpd): A venerable, highly flexible, and widely used web server. Uses .htaccess files for directory-level configuration.
    • Nginx (engine-x): Known for its high performance, efficiency, and excellent reverse proxy capabilities. Configuration is generally considered cleaner than Apache's but might have a slightly steeper learning curve initially.
    • Caddy: A modern web server known for its automatic HTTPS configuration via Let's Encrypt. Simpler configuration but less widely adopted than Apache/Nginx.
  • Requirement: Kanboard needs a web server to handle user requests and serve its PHP files.

• PHP: The scripting language Kanboard is written in. The web server needs to be configured to process PHP files.

  • Version: Kanboard requires a specific minimum PHP version (check the official Kanboard documentation for the version you intend to install, e.g., PHP >= 7.4 or >= 8.0). It's crucial to install a supported and actively maintained PHP version.
  • Required PHP Extensions: Kanboard relies on several PHP extensions for core functionality. These are modules that add capabilities to PHP. Common required extensions include:
    • pdo: For database abstraction (essential).
    • pdo_sqlite, pdo_mysql, or pdo_pgsql: Specific database drivers depending on your chosen database.
    • mbstring: For multi-byte string operations (handling different character sets).
    • gd: For image processing (e.g., user avatars, captchas).
    • openssl: For cryptographic operations (HTTPS, security features).
    • json: For handling JSON data (used extensively in web applications).
    • session: For managing user login sessions.
    • ctype: For character type checking.
    • xml: For parsing XML data (used by some plugins or core features).
    • filter: For data filtering and validation.
    • hash: For hashing algorithms (passwords).
    • dom: For manipulating HTML/XML documents.
    • zip (Optional but recommended): For handling zip archives (e.g., plugin installation, exports).
    • ldap (Optional): If you plan to use LDAP authentication.
  • Installation: These extensions are typically installed via your OS package manager (e.g., apt install php8.2-gd php8.2-mbstring on Debian/Ubuntu).

• Database: Where Kanboard stores all its data (projects, tasks, users, settings, etc.).

  • Supported Databases:
    • SQLite: A file-based database. Extremely simple to set up (often requires no extra installation beyond the pdo_sqlite PHP extension). The entire database is contained in a single file within the Kanboard data directory. Ideal for single-user or small-team setups, testing, or simplicity. Performance can degrade under very high concurrent write loads.
    • MySQL/MariaDB: Powerful, popular open-source relational databases. Offer better performance for larger installations and concurrent usage compared to SQLite. Requires installing and configuring the database server separately. MariaDB is a community-developed fork of MySQL and is generally recommended.
    • PostgreSQL: Another powerful, open-source relational database known for its standards compliance, robustness, and advanced features. Often preferred in complex enterprise environments. Also requires separate installation and configuration.
  • Choice: For beginners, SQLite is the easiest starting point. MySQL/MariaDB offers a good balance of performance and ease of use for larger setups. PostgreSQL is a solid choice if you prefer it or require its specific features.

Choosing a Deployment Method

There are two primary ways to install Kanboard:

1. Manual Installation (Archive Method):

   • Process: Download the Kanboard release archive (a .zip file) from the official website, extract it to your web server's document root (or a subdirectory), configure the web server, set file permissions, and potentially create a database.
   • Pros: Gives you a deep understanding of the components involved. Full control over the file structure and configuration. Easier to apply manual patches or modifications (though generally discouraged).
   • Cons: More steps involved, higher chance of configuration errors (permissions, web server config). Updates require manually downloading and replacing files. Managing PHP versions and extensions is manual.
   • Best For: Learners who want to understand the underlying setup, users with specific server configurations not easily met by Docker.

2. Docker Installation:

   • Process: Uses containerization technology (Docker) to package Kanboard and its dependencies (PHP, sometimes the web server) into isolated environments called containers. You typically use a pre-built Kanboard Docker image (official or community) and configure it using Docker Compose.
   • Pros: Simplifies dependency management (PHP version, extensions are pre-packaged). Easier installation and updates (docker pull, docker-compose up). Consistent environment across different machines. Can easily link with other containers (e.g., a separate database container).
   • Cons: Requires installing Docker and Docker Compose. Introduces a layer of abstraction which might hide some underlying details initially. Requires understanding basic Docker concepts (images, containers, volumes, networking).
   • Best For: Users familiar with Docker, those seeking easier dependency management and updates, complex setups involving multiple linked services.

3. Our Approach: For this "Basic" section, we will focus on the Manual Installation method using the archive. This provides the most fundamental understanding of how Kanboard interacts with the server environment. Docker will be discussed briefly as an alternative and potentially covered in more detail in advanced sections or a separate guide.

Workshop Basic Manual Installation (Linux/Apache/SQLite)

This workshop guides you through installing Kanboard manually on a typical Linux server (Debian/Ubuntu assumed) using the Apache web server and the simple SQLite database.

• Objective: To have a working Kanboard instance accessible via your server's IP address or domain name.
• Scenario: You have a fresh Debian or Ubuntu server (e.g., a VPS or a local VM) and want to install Kanboard for personal use.

• Prerequisites:

  • Access to a Linux server (Debian/Ubuntu) with sudo privileges.
  • An SSH client (like PuTTY on Windows, or the built-in ssh command on Linux/macOS) to connect to your server.
  • Basic familiarity with Linux command line.

• Steps:

  1. Connect to Your Server: Open your terminal or SSH client and connect to your server:

     ssh your_username@your_server_ip
     

     Replace your_username and your_server_ip accordingly.

  2. Update System Packages: It's always best practice to start with an up-to-date system.

     sudo apt update
     sudo apt upgrade -y
     

     The update command refreshes the list of available packages, and upgrade installs the newest versions of the packages currently installed. The -y flag automatically confirms prompts.

  3. Install Apache Web Server:

     sudo apt install apache2 -y
     

     This command installs the Apache web server package.
     • Verification: Open your web browser and navigate to http://your_server_ip. You should see the default Apache welcome page ("Apache2 Ubuntu Default Page" or similar). If not, check if Apache is running (sudo systemctl status apache2) and if any firewall is blocking port 80 (sudo ufw status). If ufw is active, allow HTTP traffic: sudo ufw allow 80.

  4. Install PHP and Required Extensions: Kanboard requires PHP and specific extensions. We'll install a recent version (e.g., PHP 8.2 - adjust if needed based on Kanboard's requirements at the time you're installing).

     # Install PHP core and the Apache module
     sudo apt install php libapache2-mod-php -y
     
     # Install required Kanboard extensions (adjust version number '8.2' if you installed a different one)
     sudo apt install php8.2-sqlite3 php8.2-mbstring php8.2-gd php8.2-xml php8.2-ctype php8.2-filter php8.2-session php8.2-json php8.2-openssl php8.2-hash php8.2-dom php8.2-zip -y
     

     • Explanation:
       • php: Installs the PHP command-line interpreter and core files.
       • libapache2-mod-php: Integrates PHP with Apache.
       • phpX.Y-sqlite3: Provides the PDO driver for SQLite.
       • The other phpX.Y-* packages install the essential extensions listed earlier.
     • Restart Apache: To make Apache aware of the new PHP module and extensions, restart it:

       sudo systemctl restart apache2
       

  5. Download Kanboard: Navigate to the official Kanboard website (https://kanboard.org/) and find the download link for the latest stable .zip archive. Alternatively, use the command line with wget. First, install wget and unzip if you don't have them:

     sudo apt install wget unzip -y
     

     Navigate to a temporary directory and download the archive (replace the URL with the actual latest version link):

     cd /tmp
     # Example URL - CHECK THE KANBOARD WEBSITE FOR THE LATEST!
     wget https://github.com/kanboard/kanboard/archive/refs/tags/v1.2.34.zip -O kanboard.zip
     

  6. Prepare Installation Directory: We'll install Kanboard in a subdirectory of Apache's default web root (/var/www/html). Let's call it kanboard.

     # Create the directory
     sudo mkdir /var/www/html/kanboard
     
     # Unzip Kanboard into the directory
     sudo unzip /tmp/kanboard.zip -d /var/www/html/kanboard
     
     # Check the unzipped folder name - it might include the version number like 'kanboard-1.2.34'
     ls /var/www/html/kanboard
     # If it created a subdirectory (e.g., 'kanboard-1.2.34'), move its contents up
     # Adjust 'kanboard-1.2.34' if the version is different
     # sudo mv /var/www/html/kanboard/kanboard-1.2.34/* /var/www/html/kanboard/
     # sudo rmdir /var/www/html/kanboard/kanboard-1.2.34 # Remove the now empty versioned directory
     # Check again
     ls /var/www/html/kanboard
     

     Sometimes the zip file extracts directly without an extra versioned folder. Check the output of ls carefully. You should now have files like index.php, config.default.php, directories like app, assets, etc., directly inside /var/www/html/kanboard.

  7. Set File Permissions: The web server needs permission to write to Kanboard's data directory. This is crucial for SQLite databases, file uploads, and cache.

     # Give ownership of the kanboard directory to the web server user (usually www-data on Debian/Ubuntu)
     sudo chown -R www-data:www-data /var/www/html/kanboard
     
     # Set appropriate permissions (directories 755, files 644 is standard, but data needs write access)
     # Find the data directory and ensure it's writable by the web server process group
     sudo find /var/www/html/kanboard/data -type d -exec chmod 775 {} \;
     sudo find /var/www/html/kanboard/data -type f -exec chmod 664 {} \;
     
     # Also ensure the main directory allows execution/access
     sudo chmod 755 /var/www/html/kanboard
     

     • Explanation: chown -R www-data:www-data changes the owner and group recursively. chmod 775 (directories) means Owner: rwx, Group: rwx, Others: r-x. chmod 664 (files) means Owner: rw-, Group: rw-, Others: r--. We give group write access (775/664) to the data directory for the www-data group.

  8. Configure Kanboard (Optional - Basic): Kanboard works out-of-the-box with SQLite without specific configuration. However, you can rename the default config file for potential future customizations.

     sudo cp /var/www/html/kanboard/config.default.php /var/www/html/kanboard/config.php
     

     For now, we don't need to edit config.php as SQLite is the default.

  9. Access Kanboard: Open your web browser and navigate to http://your_server_ip/kanboard. You should see the Kanboard login screen.

  10. Login: The default credentials are:

      • Username: admin
      • Password: admin IMPORTANT: Change the default admin password immediately after logging in! Go to the user dropdown (top right corner) -> My profile -> Change password.

• Verification: You can log in, see the Kanboard dashboard, and change the admin password.

• Troubleshooting Tips:
  • 404 Not Found: Double-check the URL. Ensure Apache is running. Verify the Kanboard files are in the correct directory (/var/www/html/kanboard). Check Apache's error log: sudo tail -f /var/log/apache2/error.log.
  • PHP Code Displayed Instead of Website: The PHP module might not be installed or enabled correctly. Check installation steps and ensure Apache was restarted. Run sudo a2enmod phpX.Y (replace X.Y with your version) and sudo systemctl restart apache2.
  • Permission Errors (e.g., cannot write to data directory): Revisit Step 7. Ensure www-data owns the files and the data directory has the correct permissions (775). SELinux or AppArmor (less common on default Debian/Ubuntu) could also be interfering if enabled.
  • Blank Page: Check both Apache's error log (/var/log/apache2/error.log) and potentially PHP's error log (location defined in php.ini, often /var/log/php/error.log or similar). This usually indicates a PHP error. Make sure all required extensions are installed and enabled.

Congratulations! You have successfully performed a basic manual installation of Kanboard. You now have a foundation to build upon as we explore its features.

2. First Steps Inside Kanboard

Now that you have Kanboard installed, it's time to familiarize yourself with the user interface and fundamental concepts. This section guides you through logging in, understanding the dashboard, creating your first project, and working with basic Kanboard elements like boards, columns, swimlanes, and tasks.

Logging In and Initial Security

As established in the workshop, you first access Kanboard via the URL you set up (e.g., http://your_server_ip/kanboard). You are greeted by the login screen.

• Default Credentials:
  • Username: admin
  • Password: admin
• CRITICAL First Step: Change the Default Admin Password!
  1. Log in using the default credentials.
  2. Locate the user menu in the top-right corner (it usually shows the username "admin"). Click on it.
  3. Select "My profile".
  4. On the left sidebar, click "Change password".
  5. Enter the current password (admin) and your new, strong password twice.
  6. Click "Save".
  7. Why is this critical? Leaving default credentials exposed is a massive security risk. Anyone finding your Kanboard instance could log in with full administrative privileges, access, modify, or delete all your project data. Always use strong, unique passwords.

Dashboard Overview

After logging in, you land on the Kanboard Dashboard. This is your central hub, providing a high-level overview of your projects and assigned tasks.

• Key Dashboard Sections (Default View):
  • My Projects: Lists the projects you are a member of. Clicking a project name takes you to its board view.
  • My Tasks: Shows tasks assigned directly to you across all your projects. This helps you focus on your immediate responsibilities.
  • My Activity Stream: Displays recent actions you've performed or events related to your tasks/projects (e.g., task creation, moves, comments).
• Navigation:
  • Top Bar: Contains the Kanboard logo (links back to the dashboard), project search, links to create new tasks/projects, and the user menu (Profile, Settings, Logout).
  • Project Menu (when inside a project): A sidebar appears on the left when you are viewing a specific project, providing access to the Board, Gantt chart (if enabled), Task List, Settings, etc., for that project.

Creating Your First Project

A "Project" in Kanboard is the primary container for a set of related tasks, typically organized around a specific goal or initiative.

• How to Create:
  1. Click the "+" icon in the top bar and select "New project".
  2. Alternatively, from the Dashboard, click the "New project" link.
  3. Enter a meaningful Project Name (e.g., "Personal Website Development", "Thesis Research", "Semester Coursework").
  4. Identifier (Optional): You can provide a short, unique identifier (e.g., PWD, THESIS, SEM). If left blank, Kanboard generates one. This can be useful for integrations or linking tasks.
  5. Click "Save".
• Project Membership: By default, the user creating the project (in this case, the admin user) is automatically added as the Project Manager. We will cover adding other users in the Intermediate section.

Understanding the Kanboard Board

The core of Kanboard is the Board view, which visualizes your workflow using the Kanban methodology. When you open a project, you typically land on its board.

• Columns:

  • Representation: Vertical lanes representing different stages of your workflow.
  • Default Columns: Kanboard usually starts with basic columns like "Backlog", "Ready", "Work in progress", and "Done".
  • Purpose: Tasks move from left to right across columns as they progress through the workflow. This provides instant visibility into the status of work.
  • Customization: You can (and should!) customize these columns to match your specific process (e.g., "To Do", "Analysis", "Development", "Testing", "Deployed"). We'll cover customization later.

• Tasks (Cards):

  • Representation: Individual units of work, displayed as cards within the columns.
  • Content: Each card typically shows the task title, assignee (if any), due date (if set), category, tags, etc. Clicking a card opens a detailed view.
  • Movement: You drag and drop task cards between columns to indicate progress.

• Swimlanes:

  • Representation: Horizontal lanes that segment the board, allowing you to group tasks within columns based on different criteria.
  • Default Swimlane: Kanboard starts with a single, default swimlane ("Default swimlane").
  • Purpose: Useful for categorizing tasks by priority, feature, user story, department, or any other relevant dimension that spans across your workflow stages. For example, you could have swimlanes for "High Priority", "Medium Priority", "Low Priority". A task stays in its swimlane as it moves across columns.
  • Customization: You can add, remove, and rename swimlanes in the project settings.

Creating, Moving, and Editing Tasks

Tasks are the lifeblood of your project board.

• Creating a Task:

  1. Navigate to the project board where you want to add the task.
  2. Click the "+" icon in the top-left corner of the column where the task should initially reside (e.g., "Backlog" or "To Do").
  3. A small form appears. Enter the Title of the task (make it clear and concise).
  4. (Optional) You can assign it to a user, set a color, add tags, etc., right away, but just the title is enough to create it.
  5. Press Enter or click "Save". The task card appears in the column.

• Moving a Task:

  1. Hover your mouse cursor over the task card you want to move.
  2. Click and hold the mouse button.
  3. Drag the card horizontally to the desired column representing its new status.
  4. Release the mouse button. The task is now in the new column. This action is usually logged in the project's activity stream.

• Editing a Task (Detailed View):

  1. Click anywhere on the task card (usually the title).
  2. A modal window or a separate page opens, showing the task details.
  3. Here you can:
     • Edit the Title and Description (add more context, requirements, links).
     • Assign the task to a Assignee (a project member).
     • Set a Due Date.
     • Add Tags for categorization or filtering.
     • Assign a Category.
     • Set a Priority.
     • Add Sub-tasks (break down the main task).
     • Add Comments.
     • Attach Files.
     • View the task's Activity history.
  4. Make your changes and click "Save" or "Update". Click "Close" or the 'X' icon to return to the board.

Workshop Your First Project Board

Let's apply these concepts by creating and managing a simple project.

• Objective: To create a project, customize its board slightly, add tasks representing steps in planning a fictional event, and move them across the board.
• Scenario: You want to use Kanboard to plan a small weekend picnic with friends.

• Prerequisites:

  • Working Kanboard installation.
  • Logged in as the admin user (or any user with project creation rights).

• Steps:

  1. Create the Project:

     • Click the "+" icon -> "New project".
     • Project Name: Weekend Picnic Planning
     • Click "Save". You will be taken to the new project's screen (likely the board view).

  2. Review Default Board:

     • Observe the default columns: "Backlog", "Ready", "Work in progress", "Done".
     • Observe the default swimlane.

  3. Add Initial Tasks (Brainstorming): Let's add some tasks to the "Backlog" column, representing things we need to figure out or do.

     • Click the "+" in the "Backlog" column header.
     • Add the following tasks one by one (just enter the title and press Enter):
       • Decide on Date
       • Choose Location
       • Create Guest List
       • Plan Food & Drinks
       • Assign Food Items
       • Send Invitations
       • Check Weather Forecast
       • Buy Supplies (Plates, Cups, etc.)
       • Confirm Guest Count
       • Coordinate Transport

  4. Start Planning (Moving Tasks): Let's say you've decided you need to pick a date and location first.

     • Drag Decide on Date from "Backlog" to "Ready".
     • Drag Choose Location from "Backlog" to "Ready".
     • Now, let's assume you are actively working on deciding the date. Drag Decide on Date from "Ready" to "Work in progress".

  5. Edit a Task (Add Details): You've chosen a location! Let's update that task.

     • Click on the Choose Location task card (currently in "Ready").
     • In the detailed view, add a Description: Research parks nearby. Check for facilities (BBQ grills, tables, restrooms). Final choice: Sunnyvale Park.
     • Click "Save".

  6. Complete a Task: You've finalized the date.

     • Drag Decide on Date from "Work in progress" to "Done".
     • You've also finalized the location. Drag Choose Location from "Ready" directly to "Done". (Sometimes tasks skip steps!).

  7. Prepare Next Steps: Now that date and location are set, guest list and food planning are next.

     • Drag Create Guest List from "Backlog" to "Ready".
     • Drag Plan Food & Drinks from "Backlog" to "Ready".

  8. Explore the Board:

     • Click around the interface. Hover over task cards to see available actions.
     • Click the project title ("Weekend Picnic Planning") in the top bar or sidebar to access project settings (we won't change them yet, just see where they are).
     • Click the Kanboard logo or "Dashboard" link to return to the main dashboard. Notice your new project listed under "My Projects".

• Verification: You have a project named "Weekend Picnic Planning". It has several tasks, some of which have been moved to "Ready" or "Done". You were able to add a description to a task.

• Reflection: You've seen how Kanboard provides a visual way to track tasks through different stages. Even with just the basic features, you can start organizing simple projects effectively. The drag-and-drop interface makes updating status intuitive.

This concludes the basic introduction to using Kanboard. You can now create projects and manage tasks. The next sections will delve into intermediate features like user management, customization, and leveraging more powerful workflow tools.

3. User Management and Permissions

As your projects grow or involve collaboration, managing who can access and modify information becomes essential. Kanboard provides a flexible system for creating users, organizing them into groups, and assigning specific roles and permissions at both the application and project levels.

Understanding Users, Groups, and Roles

• Users: Individual accounts that can log in to Kanboard. Each user has a unique username, password, and profile information (email, name). The first user created during setup is typically the admin user, who has full system privileges.
• Groups: Collections of users. Groups are primarily used for managing project access efficiently. Instead of assigning permissions to users one by one for each project, you can add users to a group and then assign the entire group to a project with a specific role. This simplifies administration, especially with many users or projects. Examples: "Development Team", "Marketing Department", "External Collaborators".
• Roles: Define the level of access and control a user or group has within Kanboard. Kanboard has two main scopes for roles:
  • Application Roles (Global Roles): Determine what a user can do across the entire Kanboard instance.
    • Administrator: Full control over the Kanboard instance, including system settings, user management, plugin installation, and access to all projects regardless of specific project permissions. (admin user has this role by default).
    • Manager: Can create new projects, manage users and groups (but not other administrators), and potentially access specific administrative settings depending on configuration.
    • User: Standard role. Can access projects they are a member of, create tasks, move tasks (according to project permissions), and manage their own profile. Cannot access administrative settings or manage users/groups. This is the most common role for team members.
  • Project Roles: Define what a user or group can do within a specific project they are assigned to. These roles are assigned when adding a user or group to a project.
    • Project Manager: Has full control over that specific project, including managing project settings (columns, swimlanes, categories, hooks), assigning users/groups to the project, and modifying/closing/opening any task within the project.
    • Project Member: Can create tasks, move tasks between columns they have access to, comment, attach files, and generally participate in the project workflow. They cannot change project settings or manage project users. This is the standard role for team participants.
    • Project Viewer: Can only view the project board, task details, and activity. Cannot create, edit, move tasks, or comment. Useful for stakeholders or external parties who need visibility but shouldn't make changes.

Creating and Managing Users

Administrators (and potentially Managers, depending on settings) can create and manage user accounts.

• Accessing User Management:
  1. Log in as an admin user.
  2. Click the gear icon (Settings) in the top-right corner (or navigate via User Menu -> Settings if the gear icon isn't present in your version/layout).
  3. In the left sidebar, click "User Management".
• Creating a New User:
  1. Click the "New user" link.
  2. Fill in the required fields:
     • Username: A unique identifier for login (e.g., jdoe, student1).
     • Name (Optional): The user's full name for display purposes (e.g., John Doe).
     • Email (Optional but Recommended): Used for notifications, password resets.
     • Password: Set an initial password for the user. They should be instructed to change it upon first login.
     • Confirmation: Re-enter the password.
     • Role: Choose the Application Role (Administrator, Manager, User). For team members, select "User".
  3. (Optional) Checkboxes:
     • Account locked: Prevents the user from logging in.
     • Administrator: Shortcut to assign the Administrator role.
     • User is manager: Shortcut to assign the Manager role.
     • Enable two-factor authentication: If 2FA is configured system-wide, you can enforce it here.
     • Notifications enabled: Controls if the user receives email notifications (requires email setup).
  4. Click "Save".
• Managing Existing Users:
  • From the "User Management" list, you can:
    • Click the Edit link next to a user to modify their details (Name, Email, Role, lock status, etc.).
    • Click the Change Password link to set a new password for the user.
    • Click the Remove link to delete the user account permanently (use with caution!).
    • Click Authentication to manage specific login methods (e.g., link to LDAP, covered later).
    • Click External accounts (relevant for external authentication).
    • Click Last logins to see login history.
    • Click Sessions to see active login sessions.

Creating and Managing Groups

Groups simplify assigning users to projects.

• Accessing Group Management:
  1. Log in as an admin user.
  2. Navigate to Settings -> "Group Management".
• Creating a New Group:
  1. Click the "New group" link.
  2. Enter a Name for the group (e.g., Research Assistants, Project Alpha Team).
  3. (Optional) External ID: Used for mapping to external group systems (like LDAP).
  4. Click "Save".
• Managing Group Membership:
  1. From the "Group Management" list, click the number in the "Users" column next to the group you want to manage.
  2. You'll see a list of users currently in the group (initially empty).
  3. In the "Add a user" dropdown, select the user you want to add to the group.
  4. Click "Add". Repeat for all users you want in this group.
  5. To remove a user, click the "Remove" link next to their name in the group list.
• Managing Existing Groups:
  • From the main "Group Management" list, you can click Edit to rename the group or change its External ID.
  • Click Remove to delete the group (this does not delete the users within the group, only the group itself and its project associations).

Project-Specific Permissions

Once you have users and potentially groups, you need to grant them access to specific projects. This is done within the project's settings.

• Accessing Project Permissions:
  1. Navigate to the project board you want to manage access for.
  2. In the left sidebar project menu, click "Settings".
  3. In the new left sidebar that appears, click "Permissions".
• Adding Users/Groups to a Project:
  1. You will see two sections: "Users" and "Groups".
  2. To add a specific user: In the "Users" section, select the user from the "Add a user" dropdown. Choose their Project Role (Project Manager, Project Member, Project Viewer) from the adjacent dropdown. Click "Add".
  3. To add an entire group: In the "Groups" section, select the group from the "Add a group" dropdown. Choose the Project Role that all members of this group will have for this project. Click "Add".
• Managing Project Permissions:
  • In the "Users" or "Groups" list within Project Permissions, you can:
    • Change the role of an existing user/group using the dropdown next to their name.
    • Remove a user/group from the project by clicking the "Remove" link next to their name. Note: Removing a user here only revokes their access to this project; it doesn't delete their account or remove them from groups.

Authentication Methods (Brief Overview)

While the default method is storing usernames and passwords in Kanboard's database, Kanboard supports other methods, often configured in config.php or via Admin settings:

• Database (Default): User credentials stored and checked within Kanboard.
• LDAP (Lightweight Directory Access Protocol): Authenticate users against an external directory server like OpenLDAP or Microsoft Active Directory. Useful in organizations with existing centralized user management. Requires the php-ldap extension and specific configuration.
• Reverse Proxy: Delegate authentication to the web server or a reverse proxy (like Apache or Nginx configured with mod_auth_basic, mod_auth_kerb, etc.). Kanboard trusts the identity provided by the proxy.
• OAuth2/OpenID Connect: Integrate with external identity providers like Google, GitHub, GitLab, etc. Users log in via their existing accounts on those platforms. Often requires specific plugins.

We focus on the Database method here. LDAP and others are more advanced topics.

Workshop Setting Up a Team Project

Let's simulate setting up a project for a small study group.

• Objective: To create user accounts for study group members, create a group for them, create a shared project, and assign the group to the project with appropriate permissions.
• Scenario: You (admin user) are setting up Kanboard for your university study group ("CompSci Seminar Group") working on a joint presentation. You need accounts for two other members, Alice and Bob.

• Prerequisites:

  • Working Kanboard installation.
  • Logged in as the admin user.

• Steps:

  1. Create User Accounts:

     • Go to Settings -> "User Management".
     • Click "New user".
     • Create Alice's account:
       • Username: alice
       • Name: Alice Wonderland
       • Email: alice@example.com (use a real email if you want notifications/password reset later)
       • Password: SecurePasswordAlice123 (use a strong one!)
       • Confirmation: SecurePasswordAlice123
       • Role: User
       • Click "Save".
     • Click "New user" again.
     • Create Bob's account:
       • Username: bob
       • Name: Bob The Builder
       • Email: bob@example.com
       • Password: SecurePasswordBob456
       • Confirmation: SecurePasswordBob456
       • Role: User
       • Click "Save".
     • Verification: You should see alice and bob listed in User Management with the role "User".

  2. Create a Group:

     • Go to Settings -> "Group Management".
     • Click "New group".
     • Name: CompSci Seminar Group
     • Click "Save".
     • Verification: The new group appears in the list.

  3. Add Users to the Group:

     • In the "Group Management" list, click the "0" in the "Users" column for "CompSci Seminar Group".
     • In the "Add a user" dropdown, select alice. Click "Add".
     • In the "Add a user" dropdown, select bob. Click "Add".
     • Verification: The user count for the group should now be "2", and Alice and Bob should be listed on the group membership page.

  4. Create the Shared Project:

     • Go back to the Dashboard (click the Kanboard logo).
     • Click "+" -> "New project".
     • Project Name: Seminar Presentation - AI Ethics
     • Click "Save".

  5. Assign Group to Project:

     • You should be in the new project's view. In the left sidebar, click "Settings".
     • In the new left sidebar, click "Permissions".
     • Scroll down to the "Groups" section.
     • In the "Add a group" dropdown, select CompSci Seminar Group.
     • In the adjacent role dropdown, select Project Member.
     • Click "Add".
     • Verification: "CompSci Seminar Group" should now be listed under Groups with the role "Project Member".

  6. (Optional) Test Login as a Team Member:

     • Log out as admin (User Menu -> Logout).
     • Log in as alice using the password you set.
     • Alice should see the "Seminar Presentation - AI Ethics" project on her dashboard. She should be able to open it, add tasks, and move tasks.
     • Try accessing administrative settings (e.g., User Management). Alice should not have permission.
     • Log out as alice.
     • Log back in as admin.

• Reflection: You've successfully created separate user accounts and organized them using a group. By assigning the group to the project with the "Project Member" role, you've granted Alice and Bob the necessary permissions to collaborate without giving them administrative access to Kanboard or full control over the project's settings. This demonstrates a scalable way to manage project access for teams.

4. Customizing Your Kanboard Instance

While Kanboard's default settings are functional, tailoring the application and individual projects to your specific needs and workflows can significantly enhance productivity and user experience. This section covers customizing general settings, project configurations (like columns, categories, tags), and extending functionality with plugins.

General Application Settings

These settings affect the entire Kanboard instance and are typically managed by Administrators.

• Accessing Application Settings:
  1. Log in as an admin user.
  2. Navigate to Settings (Gear icon or User Menu -> Settings).
  3. Explore the options in the left sidebar under the "Application Settings" category (or similar naming). Key settings include:
• Application Settings:
  • Application URL: Crucial! Set this to the exact URL users use to access Kanboard (e.g., https://kanboard.yourdomain.com). This is used for generating correct links in emails and other integrations. If you change your domain or install HTTPS later, update this value.
  • Language: Set the default language for the user interface. Users can often override this in their profile.
  • Timezone: Set the default timezone for the application. Crucial for accurate due dates and activity timestamps. Users might also override this in their profile.
  • Date Format / Time Format: Customize how dates and times are displayed throughout the application.
  • Application Name: Change the name displayed in the browser tab and potentially the header (default: "Kanboard").
  • Login Page Logo / Favicon: Customize branding by uploading your own logo images.
• Project Settings: (Global defaults)
  • Define default columns, swimlanes, categories, etc., for newly created projects. Existing projects are not affected.
• Security Settings:
  • Brute-force protection: Configure limits on failed login attempts.
  • Enable/disable Public Access: Control if boards can be made publicly viewable via a special link.
  • X-Frame-Options Header: Prevent clickjacking by controlling if Kanboard can be embedded in an iframe on other sites (usually set to SAMEORIGIN).
• Email Settings: (Covered more in Advanced Configuration)
  • Configure SMTP server details or other methods for sending email notifications (password resets, task updates).
• API Settings: (Covered more in Advanced Configuration)
  • Enable/disable the JSON-RPC API and manage API access tokens.

Project-Specific Customization

Each project can be tailored independently by Project Managers or Administrators. This allows different projects to have unique workflows, categories, etc.

• Accessing Project Settings:
  1. Navigate to the specific project board.
  2. Click "Settings" in the left project sidebar.
• Key Project Settings:
  • Edit Project: Change the project name, identifier, description, set start/end dates, or define owners.
  • Columns:
    • Purpose: Define the stages of your workflow.
    • Actions: Add new columns, rename existing ones (e.g., "Ready" -> "To Do", "Work in progress" -> "Development"), remove columns (tasks in removed columns usually move to a preceding column), and reorder columns using drag handles.
    • Task Limit (WIP Limit): Set a maximum number of tasks allowed in a column simultaneously (except typically the first and last columns). This is a core Kanban principle (Work-In-Progress limits) to prevent bottlenecks and encourage focus. When a limit is reached, Kanboard visually indicates it, discouraging moving more tasks into that column until existing ones move out.
    • Description: Add a description to clarify the purpose or exit criteria for each column.
  • Swimlanes:
    • Purpose: Horizontally segment the board for parallel categorization (e.g., by priority, feature, team member if not using assignees).
    • Actions: Add new swimlanes, rename them, remove them, and reorder them. You can also deactivate the default swimlane if you only use custom ones.
  • Categories:
    • Purpose: Assign tasks to predefined categories for filtering, reporting, and organization (e.g., "Bug", "Feature Request", "Documentation", "Meeting").
    • Actions: Add new categories, assign colors to them, edit names, or remove them. Tasks can be assigned a category during creation or editing.
  • Tags:
    • Purpose: More flexible, ad-hoc labeling compared to categories. Users can often create tags on the fly (depending on permissions). Useful for temporary flags, specific technologies, client names, etc. (e.g., "urgent", "frontend", "api", "client-xyz").
    • Actions (Management): Administrators or Project Managers can manage the list of available tags within a project (add, edit color, rename, remove) via project settings. Users typically add tags directly when editing a task.
  • Custom Fields:
    • Purpose: Add extra data fields to your tasks beyond the standard ones. Extremely powerful for capturing project-specific information.
    • Field Types: Text, Text Area, Checkbox, Number, Currency, Date, Dropdown List.
    • Example: Create a custom field called "Operating System" (Dropdown: Windows, macOS, Linux) for bug tracking, or "Estimated Hours" (Number) for time tracking.
    • Actions: Create new custom fields, define their type, name, and potential values (for dropdowns), and specify if they are required. Once created, they appear in the task detail view.
  • Automatic Actions:
    • Purpose: Automate parts of your workflow based on events. Trigger actions when tasks are created, moved, closed, etc.
    • Example Actions: Assign a color based on priority, assign a user when a task moves to a specific column, change category upon closing, notify an external system via webhook.
    • Setup: Choose an Event (e.g., "Moving a task to a specific column"), choose the Action to perform (e.g., "Assign the task to a specific user"), and configure the action parameters (e.g., select the target column and the user).
  • Permissions: (Covered in the previous section) Manage user and group access to this specific project.
  • Integrations: Configure connections to external services (e.g., GitHub, GitLab, Slack) if relevant plugins are installed.
  • Webhooks: Send task event data to external URLs (useful for custom integrations).

Extending Functionality with Plugins

Plugins are the primary way to add features and integrations not included in the Kanboard core.

• Finding Plugins:
  • Official Plugin Directory: The Kanboard website usually maintains a directory of available plugins (https://kanboard.org/plugins.html or similar).
  • GitHub Search: Many plugins are developed and hosted on GitHub. Search for "kanboard plugin".
• Installing Plugins (Requires Admin privileges):
  1. Via UI (Recommended):
     • Go to Settings -> "Plugins".
     • Click "Plugin Directory".
     • Browse or search for the desired plugin.
     • Click the "Install" button next to the plugin. Kanboard will attempt to download and extract it into the correct directory (plugins/PluginName).
  2. Manual Installation:
     • Download the plugin archive (usually a .zip file) from its source (GitHub release, plugin directory).
     • On your server, navigate to the Kanboard installation directory.
     • Extract the plugin archive into the plugins subdirectory. Make sure the extracted folder has the correct name (e.g., if the plugin is "MarkdownPlus", the folder should be plugins/MarkdownPlus). The folder should contain the plugin's code files directly inside it, not nested within another folder (e.g., plugins/MarkdownPlus/Plugin.php).
     • bash # Example using command line (adjust URL and paths) cd /var/www/html/kanboard/plugins # Example URL - FIND THE CORRECT ONE FOR THE PLUGIN! sudo wget https://github.com/kanboard/plugin-markdown-plus/archive/refs/tags/v1.0.0.zip -O markdownplus.zip sudo unzip markdownplus.zip # Rename if necessary (e.g., if it extracted to plugin-markdown-plus-1.0.0) # sudo mv plugin-markdown-plus-1.0.0 MarkdownPlus # Set permissions (important!) sudo chown -R www-data:www-data MarkdownPlus sudo find MarkdownPlus -type d -exec chmod 755 {} \; sudo find MarkdownPlus -type f -exec chmod 644 {} \; # Clean up the zip file sudo rm markdownplus.zip
     • Go back to Kanboard's UI: Settings -> "Plugins". The manually added plugin should now appear in the list.
• Managing Plugins:
  • Activation/Deactivation: Installed plugins are usually active by default. You might find options to deactivate them in the Plugins menu (though often, removing the folder is the way to "deactivate").
  • Uninstallation:
    • UI: Look for an "Uninstall" or "Remove" button in Settings -> Plugins.
    • Manual: Log in to your server via SSH and delete the plugin's folder from the plugins directory (sudo rm -rf /var/www/html/kanboard/plugins/PluginName).
  • Updates: Currently, Kanboard's core doesn't have a built-in universal plugin update mechanism via the UI. Updates usually involve repeating the manual installation process with the newer version of the plugin files (download, remove old folder, extract new folder, set permissions). Always back up before updating plugins.
• Popular Plugin Examples:
  • MarkdownPlus: Enhances text formatting options using Markdown in task descriptions and comments.
  • Calendar: Adds a calendar view of tasks based on due dates.
  • Gantt Chart: Provides a Gantt chart visualization for project timelines (might be core in some versions).
  • Theme Plugins: Change the visual appearance of Kanboard.
  • Integration Plugins: Connect Kanboard to GitHub, GitLab, Slack, Mattermost, etc.
  • Customizer: Allows adding custom CSS or JS without creating a full theme plugin.

Workshop Enhancing a Project with Customizations

Let's customize the "Weekend Picnic Planning" project and install a useful plugin.

• Objective: To tailor the project board columns, add categories and a custom field relevant to picnic planning, and install the MarkdownPlus plugin for better task descriptions.
• Scenario: Refining the workflow and information captured for the picnic project.

• Prerequisites:

  • Working Kanboard installation with the "Weekend Picnic Planning" project.
  • Logged in as admin (or a user with Project Manager role for the picnic project and Administrator role for plugin installation).

• Steps:

  1. Customize Project Columns:

     • Navigate to the "Weekend Picnic Planning" project board.
     • Go to Settings -> "Columns".
     • Rename: Click "Edit" next to "Work in progress". Change the Title to Actively Planning. Click "Save".
     • Add New Column: Click "Add a new column". Title: Waiting For Info. Task Limit: 3. Click "Save".
     • Reorder: Drag the "Waiting For Info" column handle (usually on the left) so it sits between Ready and Actively Planning.
     • Add WIP Limit: Click "Edit" next to Actively Planning. Set Task Limit to 2. Click "Save". (Limits encourage finishing tasks before starting too many new ones).
     • Verification: Go back to the project board (click "Board" in the left sidebar). You should see the new column order ("Backlog", "Ready", "Waiting For Info", "Actively Planning", "Done") and the WIP limits displayed on the relevant column headers.

  2. Add Project Categories:

     • Go to Settings -> "Categories".
     • Click "Add a new category". Name: Food. Click "Save".
     • Click "Add a new category". Name: Logistics. Click "Save".
     • Click "Add a new category". Name: Guests. Click "Save".
     • (Optional) Assign colors to the categories by clicking "Edit".
     • Verification: The categories are listed.

  3. Assign Categories to Tasks:

     • Go back to the Board.
     • Click on the Plan Food & Drinks task card (it might be in "Backlog" or "Ready").
     • In the task detail view, find the Category dropdown. Select Food. Click "Save".
     • Click on Create Guest List. Assign Category Guests. Click "Save".
     • Click on Coordinate Transport. Assign Category Logistics. Click "Save".
     • Verification: The categories might appear on the task cards on the board (depending on theme/settings).

  4. Add a Custom Field:

     • Go to Settings -> "Custom Fields".
     • Click "Add a new custom field".
     • Label: Person Responsible
     • Machine name: (leave blank, Kanboard will generate person_responsible)
     • Type: Text
     • Check the Required box (let's assume every task needs someone assigned, even if informally).
     • Click "Save".
     • Verification: The custom field is listed.

  5. Use the Custom Field:

     • Go back to the Board. Click on the Assign Food Items task.
     • In the task detail view, you should now see a field labeled "Person Responsible".
     • Enter a name, e.g., Alice. Click "Save".
     • Verification: The custom field appears and accepts input in the task details.

  6. Install and Use MarkdownPlus Plugin:

     • Go to global Settings (gear icon) -> "Plugins".
     • Click "Plugin Directory".
     • Search for MarkdownPlus.
     • Click the "Install" button next to it. Wait for the installation confirmation.
     • (If UI install fails, follow the manual installation steps outlined earlier, ensuring correct folder name MarkdownPlus and permissions.)
     • Verification (Implicit): The plugin should now be listed under "Installed Plugins". You might need to refresh the page (Ctrl+R or Cmd+R).
     • Test Markdown: Go back to the "Weekend Picnic Planning" project board. Click on any task (e.g., Plan Food & Drinks).
     • Edit the Description. Try adding Markdown formatting:

       Let's plan the food!
       
       *   Sandwiches
       *   Salad
       *   Drinks (Juice, Water)
       *   **Dessert!**
       
       We should aim for _variety_.
       
       [Link to recipes](https://example.com)
       

     • Click "Save".
     • Verification: The description in the task view should now render with bullet points, bold text, italics, and a clickable link, demonstrating the plugin is working.

• Reflection: You've seen how easy it is to adapt Kanboard's structure (columns, categories, custom fields) to fit a specific project's needs. You also learned how to extend Kanboard's core capabilities by installing a plugin, in this case enabling richer text formatting which is very useful for task details. These customization options allow Kanboard to scale from simple to-do lists to more complex project workflows.

5. Leveraging Kanboard Features for Workflow Improvement

Beyond basic task creation and movement, Kanboard offers several features designed to help you manage complexity, track details, and gain insights into your projects. This section explores subtasks, dates, communication tools, filtering/searching, and basic analytics to optimize your workflow.

Breaking Down Work with Subtasks

Complex tasks are often easier to manage when broken down into smaller, actionable steps. Kanboard's subtask feature facilitates this.

• Purpose: Divide a larger task (parent task) into smaller, manageable checklist items. Track the completion status of these individual steps.
• Creating Subtasks:
  1. Open the detailed view of the parent task you want to break down.
  2. In the left sidebar of the task view, click "Sub-tasks".
  3. Click "Add a new sub-task".
  4. Enter a Title for the sub-task (e.g., "Draft outline", "Find references", "Write introduction").
  5. (Optional) Assign the sub-task to a Assignee (can be different from the parent task assignee).
  6. (Optional) Set an Estimated Time and Time Spent.
  7. Click "Save". Repeat for all necessary sub-tasks.
• Managing Subtasks:
  • Status: Subtasks have three statuses: To-do, In progress, Done. Click the status icon next to the sub-task title to cycle through them.
  • Editing/Removing: Use the "Edit" and "Remove" links next to each sub-task.
  • Visual Indicator: The parent task card on the board often displays a small indicator showing the number of completed vs. total subtasks (e.g., "2/5").
• Benefits: Improves clarity on what needs to be done for a larger task. Allows multiple people to potentially work on different sub-tasks under one main task. Provides a sense of progress as sub-tasks are completed.

Staying on Track with Due Dates and Reminders

Assigning due dates helps prioritize work and ensures deadlines are not missed.

• Setting Due Dates:
  1. Open the detailed view of the task.
  2. Find the Due date field.
  3. Click on it to open a calendar picker, or enter the date manually in a recognized format (e.g., YYYY-MM-DD).
  4. (Optional) You can sometimes set a specific time as well.
  5. The due date will be saved automatically or after clicking "Save"/"Update".
• Visual Cues: Tasks with upcoming or overdue due dates are often highlighted on the board (e.g., yellow for upcoming, red for overdue), although this depends on the theme/settings.
• Reminders: Kanboard can potentially send email reminders about upcoming or overdue tasks if email notifications are configured (see Advanced Configuration). These are usually configured at the application level (e.g., send reminders 1 day before due date). Individual user notification preferences also play a role.
• Filtering: You can filter the board or task lists to show only tasks due soon, overdue tasks, or tasks due within a specific timeframe.

Communication and Context with Comments and Attachments

Effective collaboration requires clear communication and easy access to relevant files, all within the context of the task.

• Comments:
  • Purpose: Discuss the task, ask questions, provide updates, record decisions directly within the task's context. Avoids scattering information across emails or chat messages.
  • Adding Comments:
    1. Open the detailed view of the task.
    2. In the left sidebar, click "Comments".
    3. Enter your comment in the text box (supports Markdown if the plugin is installed).
    4. Click "Save".
  • Features: Comments are timestamped and show the author. Users can be mentioned using @username, which might trigger a notification for that user (if configured). The history of discussion is preserved with the task.
• Attachments:
  • Purpose: Attach relevant files directly to a task (e.g., mockups, documents, spreadsheets, logs, screenshots).
  • Adding Attachments:
    1. Open the detailed view of the task.
    2. In the left sidebar, click "Attachments".
    3. Click "Attach a new file".
    4. Choose the file using the "Browse..." button or drag-and-drop it onto the designated area.
    5. Click "Upload files".
  • Management: Attached files are listed with options to download or remove them. Thumbnails might be generated for images. Be mindful of server storage space and potential upload size limits configured in PHP and the web server.

Finding Information with Filters and Search

As projects grow, quickly finding specific tasks becomes crucial. Kanboard offers powerful filtering and search capabilities.

• Board Filter (Quick Filter):
  • Location: Usually a text box labeled "Filter" or similar located above the project board.
  • Functionality: Start typing to dynamically filter the tasks currently visible on the board. It typically searches task titles, IDs, assignees, categories, tags, etc.
  • Syntax: Kanboard uses a specific filter syntax (documented within Kanboard, often via a help link near the filter box). Examples:
    • status:open: Show only open tasks (not in the "Done" column, typically).
    • assignee:bob: Show tasks assigned to user "bob".
    • category:"Bug": Show tasks in the "Bug" category.
    • due:today, due:tomorrow, due:>=today, due:<"2024-12-31": Filter by due dates.
    • #123: Show task with ID 123.
    • priority:3: Show tasks with a specific priority level.
    • "search term": Search for specific text in titles or descriptions.
    • Filters can often be combined: assignee:alice status:open category:Food
  • Clearing: Clear the text box to remove the filter and see all tasks again.
• Search Page (Global Search):
  • Location: Usually accessible via a search icon or link in the main top navigation bar.
  • Functionality: Allows searching across all projects you have access to, using the same powerful filter syntax as the board filter. Results are typically displayed in a list format.

Understanding Project Performance with Analytics and Reporting

Kanboard provides basic built-in analytics to help visualize project progress and identify potential issues.

• Accessing Analytics:
  1. Navigate to the project board.
  2. In the left project sidebar, look for links like "Analytics", "Reporting", or specific chart types.

• Common Reports:

  • Cumulative Flow Diagram (CFD):
    • Purpose: Shows the distribution of tasks across different workflow columns over time. It's a key tool for identifying bottlenecks.
    • Interpretation: Each colored band represents a column. Widening bands indicate tasks accumulating in that stage (potential bottleneck). Bands shrinking towards zero indicate work being completed. Ideally, bands for intermediate stages ("Work in Progress") should remain relatively thin and parallel.
  • Burndown Chart:
    • Purpose: Tracks the remaining work (e.g., number of tasks, sum of estimated hours) over time, compared to an ideal trend line. Helps visualize progress towards completion.
    • Interpretation: The actual work line should trend downwards towards zero by the project's end date (if set). If the line stays flat or goes up, it indicates scope creep or lack of progress.
  • Lead and Cycle Time:
    • Purpose: Measures how long it takes for tasks to move through the workflow.
      • Lead Time: Time from task creation to completion.
      • Cycle Time: Time from when work actually starts on a task (e.g., moved to "Work in progress") to completion.
    • Interpretation: Helps understand the efficiency of your process. High or erratic times might indicate inefficiencies or bottlenecks. Provides data for estimating future work.
  • Task Distribution: Pie charts or bar charts showing the number of tasks per assignee, category, priority, etc. Useful for workload balancing and understanding project composition.
  • Average Time Spent in Column: Shows how long tasks typically stay in each workflow stage. Highlights stages where tasks linger.

• Limitations: Kanboard's built-in analytics are useful but may not be as sophisticated as dedicated business intelligence tools. However, they provide valuable insights directly within your project management environment.

Workshop Managing a Complex Task Workflow

Let's use these features to manage a more complex task within the "Seminar Presentation - AI Ethics" project.

• Objective: To break down the presentation task using subtasks, assign parts, set a due date, use comments for discussion, attach a reference file, and explore relevant filters and analytics.
• Scenario: The main task "Create Presentation Slides" needs to be detailed and tracked for the study group project. Alice is assigned the main task, but Bob will help with research.

• Prerequisites:

  • Working Kanboard installation with the "Seminar Presentation - AI Ethics" project.
  • Users alice and bob created and added to the "CompSci Seminar Group" with "Project Member" role for this project.
  • Logged in as admin, alice, or bob (actions may vary slightly depending on who is logged in, but assume alice is doing most steps). Suggestion: Perform steps 1-6 logged in as alice, then step 7 logged in as admin or alice.

• Steps:

  1. Create and Assign the Parent Task:

     • Navigate to the "Seminar Presentation - AI Ethics" project board.
     • In the "Ready" column, click "+" and add the task: Create Presentation Slides.
     • Click the newly created task card to open its details.
     • Assign it to Assignee: alice.
     • Set a Due date: Choose a date about two weeks from now.
     • Click "Save".

  2. Add Subtasks:

     • While viewing the "Create Presentation Slides" task, click "Sub-tasks" in the left sidebar.
     • Click "Add a new sub-task". Title: Research Key AI Ethics Issues. Assignee: bob. Save.
     • Add another sub-task. Title: Develop Presentation Outline. Assignee: alice. Save.
     • Add another sub-task. Title: Create Slides - Introduction. Assignee: alice. Save.
     • Add another sub-task. Title: Create Slides - Core Concepts. Assignee: alice. Save.
     • Add another sub-task. Title: Create Slides - Case Studies. Assignee: bob. Save.
     • Add another sub-task. Title: Create Slides - Conclusion & Q&A. Assignee: alice. Save.
     • Add another sub-task. Title: Review and Finalize Slides. Assignee: alice. Save.
     • Verification: The sub-tasks are listed. The parent task card on the board might show "0/7".

  3. Simulate Progress (Subtask Status):

     • Assume Bob has started researching. Logged in as Bob (or Alice can update), go to the task, find the "Research Key AI Ethics Issues" sub-task, and click its status icon until it shows "In progress" (usually an orange/yellow icon).
     • Assume Alice finished the outline. Logged in as Alice, find the "Develop Presentation Outline" sub-task and click its status icon until it shows "Done" (usually a green checkmark).
     • Verification: The parent task card might now show "1/7". The sub-task statuses are updated in the task view.

  4. Use Comments for Collaboration:

     • (Logged in as Bob) Go to the "Create Presentation Slides" task, click "Comments". Add a comment: @alice Found a great article on algorithmic bias, link: [example.com/article] - useful for Case Studies? Click "Save".
     • (Logged in as Alice) Go to the task, click "Comments". Add a reply: @bob Thanks! Looks perfect. Please add it to the Case Studies slides when you get to them. Click "Save".
     • Verification: The comments appear in the task's comment history. Alice might receive a notification about the mention (if email is configured).

  5. Attach a Reference File:

     • (Logged in as Alice) Go to the "Create Presentation Slides" task, click "Attachments".
     • Click "Attach a new file". Browse and select a relevant PDF or document (you can create a dummy text file for this).
     • Click "Upload files".
     • Verification: The file is listed under Attachments.

  6. Filter the Board:

     • Go back to the project board.
     • In the filter box above the board, type assignee:bob. Only tasks and sub-tasks assigned to Bob should remain visible (specifically, the main task might still show if Bob is assigned any subtask, or only the subtasks might filter depending on Kanboard version/config - observe the behavior. Also the subtasks Bob was assigned within Alice's main task). Correction: Filters typically apply to main tasks. To see Bob's work specifically, it might be better to check his dashboard or use a more specific filter if available.
     • Clear the filter. Now type due:<= followed by the date you set (or use due:next-week, due:this-month if supported). The "Create Presentation Slides" task should be visible.
     • Clear the filter. Type status:open. All tasks except those in the "Done" column should be visible.

  7. Explore Analytics (Basic):

     • In the left project sidebar, click "Analytics" or "Cumulative flow". Observe the chart. Since the project is new, it might not be very informative yet, but you can see the initial distribution of tasks.
     • If available, click "Lead and Cycle time". It will likely show "N/A" or 0 until tasks are actually completed.
     • Click "Task distribution". See the breakdown by assignee (should show tasks assigned to admin, alice, bob).
     • Verification: You can access the analytics pages and see the initial state of the reports.

• Reflection: You've experienced how subtasks add granularity to complex work. Comments and attachments provide essential context and collaboration tools directly linked to the task. Filters help manage larger boards, and even basic analytics start giving insights as the project progresses. Using these features effectively moves you from simple task listing to more robust project management.

6. Advanced Configuration and Integration

With Kanboard running and customized, this section delves into more advanced configurations focusing on security, performance, and integration capabilities. These steps often involve interacting more directly with the server environment and Kanboard's configuration files.

Enhancing Security with HTTPS/SSL

Running Kanboard over HTTPS (HTTP Secure) is essential for protecting login credentials and sensitive project data from eavesdropping. It encrypts the communication between the user's browser and your server. The easiest way to achieve this is typically using Let's Encrypt, which provides free SSL/TLS certificates.

• Concept:
  • SSL/TLS Certificates: Digital certificates that verify your server's identity and enable encrypted connections.
  • Let's Encrypt: A free, automated, and open Certificate Authority (CA).
  • Certbot: A client tool that automates the process of obtaining and renewing Let's Encrypt certificates and configuring web servers (Apache, Nginx) to use them.
• Prerequisites:
  • Domain Name: You need a registered domain name (e.g., kanboard.yourdomain.com) pointing to your server's public IP address via DNS records (an 'A' record). Let's Encrypt needs to verify domain ownership. Using an IP address directly generally doesn't work for standard, trusted certificates.
  • Web Server: Apache or Nginx correctly configured to serve your Kanboard instance over HTTP (as set up previously).
  • Server Access: sudo or root access to your server.
  • Port 80 Open: Let's Encrypt often uses Port 80 for domain validation (HTTP-01 challenge).

• Steps (using Certbot on Debian/Ubuntu with Apache):

  1. Install Certbot and Apache Plugin:

     sudo apt update
     sudo apt install certbot python3-certbot-apache -y
     

  2. Configure Apache Virtual Host (if not done properly): Ensure you have a proper Apache Virtual Host configuration file for your domain (e.g., /etc/apache2/sites-available/kanboard.conf) that includes ServerName your.domain.com. If you installed Kanboard in a subdirectory (/var/www/html/kanboard), Certbot might still work, but having a dedicated Virtual Host is cleaner. Example /etc/apache2/sites-available/kanboard.conf (for Kanboard at /var/www/kanboard):

     <VirtualHost *:80>
         ServerAdmin webmaster@localhost
         ServerName kanboard.yourdomain.com
         DocumentRoot /var/www/kanboard
     
         <Directory /var/www/kanboard>
             Options Indexes FollowSymLinks
             AllowOverride All # Important for Kanboard's .htaccess/routing
             Require all granted
         </Directory>
     
         ErrorLog ${APACHE_LOG_DIR}/kanboard_error.log
         CustomLog ${APACHE_LOG_DIR}/kanboard_access.log combined
     </VirtualHost>
     

     • Enable the site: sudo a2ensite kanboard.conf
     • Enable rewrite module: sudo a2enmod rewrite
     • Restart Apache: sudo systemctl restart apache2
     • Adapt DocumentRoot and <Directory> path if you used /var/www/html/kanboard.

  3. Run Certbot:

     sudo certbot --apache -d kanboard.yourdomain.com
     

     • Replace kanboard.yourdomain.com with your actual domain/subdomain.
     • Certbot will ask for your email address (for renewal reminders).
     • Agree to the Terms of Service.
     • It will ask if you want to redirect HTTP traffic to HTTPS. Choose Redirect (option 2) - this is highly recommended for security.
  4. Verification: Certbot should report success and that the certificate has been deployed. It will automatically modify your Apache configuration to include the SSL certificate paths and the redirect. Try accessing https://kanboard.yourdomain.com. Your browser should show a padlock icon, indicating a secure connection. Also try http://kanboard.yourdomain.com - it should automatically redirect to HTTPS.
  5. Automatic Renewal: Certbot automatically sets up a systemd timer or cron job to attempt renewal periodically. You can test the renewal process (without actually renewing unless needed):

     sudo certbot renew --dry-run
     

  6. Update Kanboard Application URL: Go back to Kanboard -> Settings -> Application Settings -> Application URL and update it to use https:// (e.g., https://kanboard.yourdomain.com).

Web Server Configuration Best Practices

Beyond HTTPS, consider these web server configurations:

• Security Headers: Add headers to instruct browsers on security policies. Common headers (often added within your Apache VirtualHost or Nginx server block):
  • Strict-Transport-Security (HSTS): Tells browsers to only connect via HTTPS for a specified duration. Add this after confirming HTTPS works perfectly. Example (Apache): Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains" (Requires mod_headers).
  • Content-Security-Policy (CSP): Restricts where resources (scripts, images, styles) can be loaded from, mitigating cross-site scripting (XSS). Can be complex to configure correctly without breaking functionality. Start restrictive and test thoroughly.
  • X-Content-Type-Options: nosniff: Prevents browsers from MIME-sniffing the content type.
  • X-Frame-Options: SAMEORIGIN or DENY: Prevents clickjacking (already mentioned).
  • Referrer-Policy: strict-origin-when-cross-origin or same-origin: Controls how much referrer information is sent.
• Disable Unnecessary Modules/Features: Reduce the attack surface by disabling Apache/Nginx modules you don't need.
• File Access Restrictions: Ensure your web server configuration only grants access to necessary files. Kanboard's .htaccess file (Apache) or location blocks (Nginx) often handle restricting direct access to directories like data, app, etc. Double-check these are effective.
• PHP Configuration (php.ini):
  • expose_php = Off: Hides the PHP version in HTTP headers.
  • display_errors = Off (for production): Prevents potentially sensitive error details from being shown to users. Log errors instead (log_errors = On, error_log = /path/to/php_error.log).
  • upload_max_filesize, post_max_size: Adjust based on how large attachments you need to allow, but don't set excessively high.
  • session.cookie_secure = On (if using HTTPS): Ensures session cookies are only sent over HTTPS.
  • session.cookie_httponly = On: Prevents client-side scripts from accessing the session cookie.

Database Choice and Optimization Considerations

While SQLite is simple, MySQL/MariaDB or PostgreSQL offer better performance and scalability for larger or more active instances.

• Switching Databases (Example: SQLite to MySQL):
  • Backup First! Always back up your existing Kanboard (data directory for SQLite, files, potentially database dump if already using SQL).
  • Install MySQL/MariaDB server: sudo apt install mariadb-server
  • Secure the installation: sudo mysql_secure_installation (set root password, remove anonymous users, etc.)
  • Create a database and user for Kanboard:

    sudo mysql -u root -p
    -- Enter the root password you just set
    
    CREATE DATABASE kanboard CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'kanboard_user'@'localhost' IDENTIFIED BY 'YourStrongPassword';
    GRANT ALL PRIVILEGES ON kanboard.* TO 'kanboard_user'@'localhost';
    FLUSH PRIVILEGES;
    EXIT;
    

  • Install the required PHP extension: sudo apt install php8.2-mysql (adjust version). Restart Apache: sudo systemctl restart apache2.
  • Edit Kanboard's config.php:

    // === Database ===
    // Driver: sqlite, mysql or postgres (case sensitive)
    define('DB_DRIVER', 'mysql'); // Change from 'sqlite'
    
    // Mysql/Postgres username
    define('DB_USERNAME', 'kanboard_user');
    
    // Mysql/Postgres password
    define('DB_PASSWORD', 'YourStrongPassword');
    
    // Mysql/Postgres hostname
    define('DB_HOSTNAME', 'localhost');
    
    // Mysql/Postgres database name
    define('DB_NAME', 'kanboard');
    
    // Mysql/Postgres custom port (comment to use default port)
    // define('DB_PORT', '3306');
    
    // SQLite specifc: Leave empty for MySQL/Postgres
    // define('DB_FILENAME', '/path/to/kanboard/data/db.sqlite');
    

  • Data Migration: Kanboard does not have a built-in, one-click migration tool between database types. You would typically need to:
    1. Start with the new, empty MySQL database configured.
    2. Log in to the (now empty) Kanboard instance as admin.
    3. Manually recreate projects, users, settings OR attempt a complex export/import if possible (e.g., export projects individually if that feature exists, potentially export/import users via CSV if a plugin supports it). Data migration between different DB types is often non-trivial. For existing complex instances, careful planning or third-party tools might be needed. It's often easier to start fresh on the new database type.
• Basic Optimization:
  • Database Server Tuning: Default MySQL/MariaDB/PostgreSQL settings are often conservative. Tuning parameters like innodb_buffer_pool_size (MySQL/MariaDB) or shared_buffers (PostgreSQL) based on your server's RAM can significantly improve performance. This requires research specific to the database and your hardware.
  • Indexing: Kanboard's database schema includes indexes on frequently queried columns. Ensure these are maintained. Database administration tools can help analyze query performance.
  • Regular Maintenance: Run database maintenance tasks (e.g., OPTIMIZE TABLE in MySQL, VACUUM in PostgreSQL) periodically.

Setting Up Email Notifications (SMTP)

For password resets, task notifications, and reminders, Kanboard needs to be able to send emails. Using an external SMTP server is the most reliable method.

• Prerequisites:
  • An SMTP service provider. Options:
    • Transactional Email Services: SendGrid, Mailgun, Postmark (often have free tiers). Reliable deliverability.
    • Your own email provider (Gmail, Outlook): May have sending limits or require specific security settings (like "App Passwords" for Gmail if 2FA is enabled). Less ideal for application sending.
    • Your own mail server (advanced setup).
  • SMTP Credentials: Server address (e.g., smtp.sendgrid.net), port (e.g., 587 for TLS, 465 for SSL), username, password, and encryption type (TLS or SSL).
• Configuration (config.php):

  // Mail configuration
  // Driver: "smtp", "sendmail", "mail" (PHP mail function), or "log"
  define('MAIL_DRIVER', 'smtp'); // Use 'smtp'
  
  // Sender email address
  define('MAIL_FROM', 'kanboard@yourdomain.com'); // Use an address you can send from
  
  // SMTP configuration (if MAIL_DRIVER = smtp)
  define('MAIL_SMTP_HOSTNAME', 'smtp.example.com'); // Your SMTP server address
  define('MAIL_SMTP_PORT', 587); // Use 587 for TLS, 465 for SSL
  define('MAIL_SMTP_USERNAME', 'your_smtp_username');
  define('MAIL_SMTP_PASSWORD', 'your_smtp_password');
  define('MAIL_SMTP_ENCRYPTION', 'tls'); // Use 'tls' or 'ssl' (must match port)
  // define('MAIL_SMTP_HELO_NAME', null); // Usually not needed
  

• Configuration (via UI - if available):
  • Some Kanboard versions might allow configuring email settings via Settings -> Email Settings in the Admin UI, which then updates config.php. Check the UI first.
• Testing:
  • Go to Settings -> Email Settings (or similar). Look for a "Test Email" button.
  • Alternatively, trigger an action that sends email (e.g., request a password reset for a user with a valid email address). Check the recipient's inbox (and spam folder). Check Kanboard logs and mail server logs if emails fail.
• Troubleshooting: Firewall blocking outgoing SMTP ports? Incorrect credentials? Incorrect encryption/port combination? Sender address not authorized by SMTP provider? PHP openssl extension missing/misconfigured?

API Usage and Webhooks Introduction

Kanboard provides ways to interact with it programmatically.

• JSON-RPC API:
  • Purpose: Allows external applications or scripts to interact with Kanboard data (create tasks, move tasks, get project info, etc.).
  • Enabling: Settings -> API -> Enable API access.
  • Authentication: Requires an API token, generated under User Profile -> API.
  • Usage: Send JSON-RPC formatted requests (usually via HTTP POST) to the API endpoint (typically your-kanboard-url/jsonrpc.php). Requires understanding the API methods documented on the Kanboard website.
  • Example Use Cases: Custom reporting tools, integrating with other internal systems, automating task creation from external events.
• Webhooks:
  • Purpose: Kanboard sends data out to a specified URL when certain events occur within Kanboard (e.g., task created, task moved, comment added).
  • Configuration: Configured within Project Settings -> Webhooks.
  • Setup: Specify the target URL (your external application's endpoint) and select the events that should trigger the webhook.
  • Payload: Kanboard sends a JSON payload containing information about the event and the associated task/project to the target URL.
  • Example Use Cases: Triggering CI/CD pipelines when a task moves to "Deploy", updating a chat room (like Slack/Mattermost via their incoming webhooks), synchronizing data with another system.

Workshop Securing and Integrating Kanboard

Let's secure the Kanboard installation with HTTPS and configure email notifications.

• Objective: To enable HTTPS using Let's Encrypt/Certbot and configure Kanboard to send emails via SMTP for notifications.
• Scenario: Making your "Weekend Picnic Planning" or "Seminar Presentation" Kanboard instance secure and capable of sending notifications.

• Prerequisites:

  • Working Kanboard installation accessible via HTTP.
  • A registered domain name pointing to your server's IP.
  • sudo access to the server (Debian/Ubuntu with Apache assumed).
  • SMTP credentials from an email provider or service.

• Steps:

  1. Obtain and Install SSL Certificate (Let's Encrypt):

     • (If not already done) Ensure your domain's DNS 'A' record points to your server IP. Wait for DNS propagation.
     • Connect to your server via SSH.
     • Install Certbot: sudo apt update && sudo apt install certbot python3-certbot-apache -y
     • Ensure Apache config is ready (dedicated VirtualHost for your domain is recommended, see example above). Enable site and rewrite module: sudo a2ensite your-site.conf && sudo a2enmod rewrite && sudo systemctl restart apache2.
     • Run Certbot: sudo certbot --apache -d your.kanboard.domain.com
     • Follow prompts (email, ToS, choose Redirect option).
     • Verification: Access https://your.kanboard.domain.com. Check for padlock. Check HTTP redirects to HTTPS.

  2. Update Kanboard Application URL:

     • Log in to Kanboard via the new HTTPS URL.
     • Go to Settings -> Application Settings.
     • Set Application URL to https://your.kanboard.domain.com.
     • Click "Save".

  3. Configure SMTP:

     • Decide on your SMTP provider and gather credentials (server, port, username, password, encryption). For this example, let's assume:
       • Server: smtp.mailtrap.io (Mailtrap is good for testing)
       • Port: 587
       • Encryption: tls
       • Username: mailtrap-username
       • Password: mailtrap-password
       • Sender: kanboard-noreply@your.kanboard.domain.com (use your domain)
     • Edit the Kanboard configuration file:

       sudo nano /var/www/html/kanboard/config.php
       # Or /var/www/kanboard/config.php if you used a different root
       

     • Find or add the mail configuration section and update it:

       // Mail configuration
       define('MAIL_DRIVER', 'smtp');
       define('MAIL_FROM', 'kanboard-noreply@your.kanboard.domain.com'); // Change domain
       define('MAIL_SMTP_HOSTNAME', 'smtp.mailtrap.io'); // Use your provider
       define('MAIL_SMTP_PORT', 587);                   // Use your provider's port
       define('MAIL_SMTP_USERNAME', 'mailtrap-username');  // Use your username
       define('MAIL_SMTP_PASSWORD', 'mailtrap-password');  // Use your password
       define('MAIL_SMTP_ENCRYPTION', 'tls');            // Use 'tls' or 'ssl'
       

     • Save the file (Ctrl+O in nano, then Enter) and Exit (Ctrl+X).
     • Ensure PHP openssl is enabled (it usually is by default).
     • Ensure firewall allows outgoing connections on port 587 (or 465 if using SSL). Example using ufw: sudo ufw allow out 587/tcp.

  4. Test Email Sending:

     • Log in to Kanboard.
     • Go to Settings -> Email Settings (if it exists in your version). Try the test button.
     • Alternatively: Go to User Management, edit a user (e.g., alice), ensure they have a valid email address you can access. Log out. On the login page, click "Password reset". Enter Alice's username or email.
     • Check the recipient's email inbox (and spam). If using Mailtrap, check your Mailtrap inbox. You should receive the password reset email.
     • Verification: Email is successfully sent and received.

• Reflection: You have significantly hardened your Kanboard installation by implementing HTTPS, ensuring data privacy. You also enabled a crucial feature – email notifications – by configuring SMTP, which is vital for password recovery and user notifications. These steps move your self-hosted instance towards a production-ready state.

7. Backup, Restore, and Updates

Maintaining a self-hosted application requires diligent backup procedures and a safe update strategy. Losing project data can be catastrophic, and staying updated is crucial for security patches and new features. This section covers how to back up Kanboard, restore it if needed, and perform updates safely.

Importance of Backups

• Data Loss Prevention: Hardware failure, software bugs, accidental deletion, security breaches – many things can lead to data loss. Regular backups are your safety net.
• Disaster Recovery: If your server becomes completely inaccessible or corrupted, a recent backup allows you to restore your Kanboard instance on a new server.
• Testing Updates/Changes: Before major updates or configuration changes, taking a backup allows you to roll back if something goes wrong.

Backup Strategies What to Back Up

A complete Kanboard backup consists of two main parts:

1. Database: Contains all your projects, tasks, users, comments, settings, etc.
   • SQLite: Backing up the database is as simple as copying the SQLite database file. By default, this file is located at data/db.sqlite within your Kanboard installation directory.
   • MySQL/MariaDB: Requires using database-specific tools (like mysqldump) to create a logical dump (SQL file) of your Kanboard database.
   • PostgreSQL: Requires using database-specific tools (like pg_dump) to create a dump of your Kanboard database.
2. Uploaded Files (Data Directory): Contains user-uploaded attachments, plugin data, etc.
   • Located in the data directory within your Kanboard installation directory (the same place as the SQLite file, if using SQLite). It's crucial to back up this entire directory, excluding the database file if you are backing it up separately (especially for MySQL/Postgres).
3. (Optional but Recommended) Configuration File: Back up your config.php file, which contains your specific database connections, mail settings, security keys, etc.
4. (Optional) Plugins: While plugins can often be re-downloaded, backing up the plugins directory ensures you have the exact versions you were using, especially if some are manually installed or modified (though modification is discouraged).

Performing Backups

• Frequency: Depends on how critical the data is and how often it changes. For active projects, daily backups are recommended. For less active personal use, weekly might suffice.
• Location: Store backups on a separate physical location from the Kanboard server itself (e.g., another server, cloud storage like AWS S3, Backblaze B2, Dropbox, a dedicated backup NAS). Storing backups on the same server offers little protection against hardware failure or server-wide compromise.

• Method 1: Manual Backup (Example: SQLite)

  1. Connect to your server via SSH.
  2. Navigate to the Kanboard installation directory:

     cd /var/www/html/kanboard # Or your actual path
     

  3. Create a timestamped backup directory (on a separate mounted drive or path if possible):

     # Example: Backup to /mnt/backups/kanboard
     TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
     BACKUP_DIR="/mnt/backups/kanboard/kanboard_backup_$TIMESTAMP"
     sudo mkdir -p "$BACKUP_DIR"
     

  4. Copy the database file and data directory:

     # Stop the web server briefly to ensure data consistency (optional but recommended for SQLite)
     # sudo systemctl stop apache2
     
     sudo cp data/db.sqlite "$BACKUP_DIR/"
     # Copy the rest of the data directory, excluding the db file itself if copied separately
     sudo rsync -av --exclude 'db.sqlite' data/ "$BACKUP_DIR/data/"
     sudo cp config.php "$BACKUP_DIR/"
     # Optional: Backup plugins
     # sudo cp -R plugins "$BACKUP_DIR/"
     
     # Restart the web server if stopped
     # sudo systemctl start apache2
     

  5. (Optional) Compress the backup:

     sudo tar -czvf "$BACKUP_DIR.tar.gz" -C "/mnt/backups/kanboard" "kanboard_backup_$TIMESTAMP"
     sudo rm -rf "$BACKUP_DIR" # Remove the uncompressed folder if desired
     

  6. Transfer the backup offsite: Use tools like scp, rsync, or specific cloud storage CLI tools to move /mnt/backups/kanboard/kanboard_backup_$TIMESTAMP.tar.gz to your secure backup location.

• Method 2: Manual Backup (Example: MySQL/MariaDB)

  1. Connect to your server via SSH.
  2. Create a timestamped backup directory: (As above)

     TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
     BACKUP_DIR="/mnt/backups/kanboard/kanboard_backup_$TIMESTAMP"
     sudo mkdir -p "$BACKUP_DIR"
     

  3. Dump the database:

     sudo mysqldump -u kanboard_user -p'YourStrongPassword' --databases kanboard > "$BACKUP_DIR/kanboard_db_dump.sql"
     # Replace user, password, and database name with your actual values
     # Note: Storing password on command line is insecure; consider using ~/.my.cnf
     

  4. Copy the data directory (excluding cache/logs if desired) and config:

     sudo rsync -av data/ "$BACKUP_DIR/data/" # Or be more specific excluding cache etc.
     sudo cp config.php "$BACKUP_DIR/"
     # Optional: Backup plugins
     # sudo cp -R plugins "$BACKUP_DIR/"
     

  5. Compress and Transfer: (As above)

• Method 3: Automated Backup (Scripting)

  • Create a shell script (.sh) that performs the steps from Method 1 or 2.
  • Use cron (the Linux task scheduler) to run this script automatically on your desired schedule (e.g., daily at 2 AM).
  • The script should include steps to:
    • Create timestamped backup names/directories.
    • Perform the database dump (if applicable).
    • Copy necessary files/directories (data, config.php, plugins).
    • Compress the backup.
    • Transfer the backup to the remote location.
    • (Important) Implement retention logic: Automatically delete old backups (e.g., keep daily backups for 7 days, weekly for 4 weeks, monthly for 6 months) to avoid filling up backup storage.
    • (Important) Add logging and error handling to the script to notify you if backups fail.

Restoring from Backup

Restoration is needed after data loss, server failure, or a failed update. Always test your restore process periodically to ensure your backups are valid and you know the procedure.

• Steps (Example: Restoring SQLite Backup to a NEW server/instance):

  1. Set up a fresh Kanboard environment: Install the OS, web server, PHP (same major version and extensions as the original if possible), and download the same version of Kanboard code that the backup was taken from. Do not run the Kanboard installer/login yet.
  2. Retrieve the backup file: Copy the desired backup archive (e.g., kanboard_backup_YYYYMMDD_HHMMSS.tar.gz) to the new server.
  3. Extract the backup:

     # Example: Extract to /tmp
     cd /tmp
     sudo tar -xzvf /path/to/your/kanboard_backup_YYYYMMDD_HHMMSS.tar.gz
     

  4. Place the restored files:
     • Remove the default data and plugins directories and config.php from the fresh Kanboard code directory.
     • Copy the backed-up db.sqlite, data directory contents, config.php, and plugins directory (if backed up) into the Kanboard code directory (/var/www/html/kanboard or similar).

       KANBOARD_DIR="/var/www/html/kanboard" # Adjust path
       BACKUP_SOURCE="/tmp/kanboard_backup_YYYYMMDD_HHMMSS" # Adjust path
       
       sudo rm -rf "$KANBOARD_DIR/data" "$KANBOARD_DIR/plugins" "$KANBOARD_DIR/config.php"
       sudo cp "$BACKUP_SOURCE/db.sqlite" "$KANBOARD_DIR/data/"
       sudo cp -R "$BACKUP_SOURCE/data/"* "$KANBOARD_DIR/data/"
       sudo cp "$BACKUP_SOURCE/config.php" "$KANBOARD_DIR/"
       # Optional: Restore plugins
       # sudo cp -R "$BACKUP_SOURCE/plugins" "$KANBOARD_DIR/"
       

  5. Set Permissions: Crucially, reset the ownership and permissions for the restored files so the web server can access them.

     sudo chown -R www-data:www-data "$KANBOARD_DIR"
     sudo find "$KANBOARD_DIR/data" -type d -exec chmod 775 {} \;
     sudo find "$KANBOARD_DIR/data" -type f -exec chmod 664 {} \;
     # Adjust permissions for plugins if restored
     sudo find "$KANBOARD_DIR/plugins" -type d -exec chmod 755 {} \;
     sudo find "$KANBOARD_DIR/plugins" -type f -exec chmod 644 {} \;
     

  6. Restart Web Server: sudo systemctl restart apache2
  7. Test: Access Kanboard via your browser. Log in and verify that your projects, tasks, and settings are restored.

• Steps (Example: Restoring MySQL/MariaDB): Similar process, but instead of copying db.sqlite, you import the SQL dump:

  1. Set up fresh environment (OS, web server, PHP, MySQL/MariaDB, Kanboard code - same version).
  2. Create the empty database and user in MySQL/MariaDB (as shown in section 6).
  3. Import the SQL dump:

     sudo mysql -u kanboard_user -p'YourStrongPassword' kanboard < /path/to/your/kanboard_db_dump.sql
     

  4. Restore the data directory contents (excluding database file), config.php, and optionally plugins.
  5. Set permissions and restart the web server.
  6. Test thoroughly.

Updating Kanboard Safely

Updating keeps your instance secure and provides new features. The process typically involves replacing the Kanboard application code while preserving your data and configuration.

• Official Update Documentation: Always consult the official Kanboard documentation for the specific update instructions relevant to the version you are upgrading from and to. Major version upgrades might have specific steps or potential breaking changes.

• General Update Steps (Manual/Archive Method):

  1. BACKUP FIRST! Perform a full backup (Database + data + config.php + plugins) before starting the update.
  2. Check Requirements: Read the release notes for the new version. Note any changes in PHP version requirements or required extensions. Update PHP/extensions before updating Kanboard if necessary.
  3. (Optional but Recommended) Enable Maintenance Mode: If possible and supported (check docs or config.php options), enable maintenance mode to prevent users from accessing Kanboard during the update. Alternatively, stop the web server temporarily.
  4. Download New Version: Download the .zip archive of the new Kanboard version.
  5. Extract New Version: Extract the downloaded archive to a temporary location on your server (e.g., /tmp/kanboard-new).
  6. Replace Core Files:
     • Go to your current Kanboard installation directory (/var/www/html/kanboard).
     • Delete all existing Kanboard files and directories EXCEPT for:
       • data directory
       • plugins directory
       • config.php file
     • Copy all files and directories from the new version's extracted folder (/tmp/kanboard-new) into your current Kanboard installation directory, overwriting existing core files but leaving your data, plugins, and config.php untouched.

       # CAUTION: Ensure you are in the correct directory!
       # cd /var/www/html/kanboard
       # Example commands (adapt paths, use with extreme care):
       # Find files/dirs to keep:
       # mv data /tmp/kb_data_backup
       # mv plugins /tmp/kb_plugins_backup
       # mv config.php /tmp/kb_config_backup
       # Remove everything else:
       # rm -rf * .* # Be VERY careful with rm -rf *
       # Copy new files:
       # cp -R /tmp/kanboard-new/* .
       # Restore kept items:
       # mv /tmp/kb_data_backup data
       # mv /tmp/kb_plugins_backup plugins
       # mv /tmp/kb_config_backup config.php
       #
       # A safer approach might be:
       # 1. cd /var/www/html
       # 2. mv kanboard kanboard_old
       # 3. mkdir kanboard
       # 4. cp -R /tmp/kanboard-new/* kanboard/
       # 5. cp kanboard_old/config.php kanboard/
       # 6. mv kanboard_old/data kanboard/
       # 7. mv kanboard_old/plugins kanboard/
       # 8. # Set permissions on the new kanboard directory
       

  7. Set Permissions: After copying the new files, ensure the file ownership and permissions are correct for the entire Kanboard directory, especially the data and plugins directories.

     sudo chown -R www-data:www-data /var/www/html/kanboard
     # Rerun find commands for permissions if needed
     

  8. Database Migrations: Log in to Kanboard as an administrator. Kanboard usually detects the version change and may automatically run necessary database schema migrations. Follow any on-screen prompts. This step is critical. Check logs if errors occur.
  9. Test Thoroughly: Clear your browser cache. Test all core functionalities: logging in, viewing boards, creating/moving tasks, checking settings, testing plugins.
  10. Disable Maintenance Mode / Restart Web Server: If you stopped the server or enabled maintenance mode, disable/restart it now.

• Updating with Docker: Generally simpler. Pull the new Docker image version specified in your docker-compose.yml file, then run docker-compose down and docker-compose up -d. Docker handles replacing the application code container. Ensure your data directory is mapped as a persistent volume so it's not lost. Database migrations should still run automatically on the first start with the new image. Always back up persistent volumes before updating Docker containers.

Workshop Implementing a Backup Routine (Manual Simulation)

Let's simulate the manual backup process for our Kanboard instance (assuming SQLite for simplicity).

• Objective: To perform a manual backup of the Kanboard database, data directory, and configuration file.
• Scenario: Performing a scheduled backup before attempting a major configuration change or update.

• Prerequisites:

  • Working Kanboard installation (using SQLite).
  • sudo access to the server via SSH.
  • A designated backup location (we'll use /opt/kanboard_backups for this example - create it if it doesn't exist: sudo mkdir -p /opt/kanboard_backups && sudo chmod 700 /opt/kanboard_backups).

• Steps:

  1. Connect to Server:

     ssh your_username@your_server_ip
     

  2. Define Variables (Optional, but good practice):

     KANBOARD_DIR="/var/www/html/kanboard" # Adjust if your path is different
     BACKUP_BASE_DIR="/opt/kanboard_backups"
     TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
     BACKUP_DEST_DIR="$BACKUP_BASE_DIR/kanboard_backup_$TIMESTAMP"
     

  3. Create Backup Directory:

     echo "Creating backup directory: $BACKUP_DEST_DIR"
     sudo mkdir "$BACKUP_DEST_DIR"
     

  4. Stop Web Server (Optional but Recommended for SQLite):

     echo "Stopping web server..."
     sudo systemctl stop apache2 # Or nginx if using Nginx
     # Wait a second for processes to terminate
     sleep 1
     

  5. Copy Kanboard Data:

     echo "Copying Kanboard database..."
     sudo cp "$KANBOARD_DIR/data/db.sqlite" "$BACKUP_DEST_DIR/"
     
     echo "Copying Kanboard data directory (excluding db)..."
     sudo rsync -av --exclude 'db.sqlite' "$KANBOARD_DIR/data/" "$BACKUP_DEST_DIR/data/"
     
     echo "Copying Kanboard config file..."
     sudo cp "$KANBOARD_DIR/config.php" "$BACKUP_DEST_DIR/"
     
     echo "Copying Kanboard plugins directory..."
     sudo cp -R "$KANBOARD_DIR/plugins" "$BACKUP_DEST_DIR/plugins/"
     

  6. Restart Web Server:

     echo "Starting web server..."
     sudo systemctl start apache2 # Or nginx
     

  7. Verify Backup Files:

     echo "Listing backup contents:"
     sudo ls -lR "$BACKUP_DEST_DIR"
     

     Check that db.sqlite, config.php, the data directory contents (like files, cache), and the plugins directory are present.

  8. Compress Backup (Optional):

     echo "Compressing backup..."
     sudo tar -czvf "$BACKUP_DEST_DIR.tar.gz" -C "$BACKUP_BASE_DIR" "kanboard_backup_$TIMESTAMP"
     echo "Removing uncompressed directory..."
     sudo rm -rf "$BACKUP_DEST_DIR"
     echo "Compressed backup created at: $BACKUP_DEST_DIR.tar.gz"
     sudo ls -lh "$BACKUP_DEST_DIR.tar.gz"
     

  9. Simulate Offsite Transfer (Conceptual):

     • You would now use scp or rsync to copy $BACKUP_DEST_DIR.tar.gz to another machine or cloud storage.
     • Example using scp to another server backup_server:

       # sudo scp "$BACKUP_DEST_DIR.tar.gz" backup_user@backup_server:/path/on/backup/server/
       

• Reflection: You have manually executed the steps for a complete Kanboard backup. While manual backups are feasible, automating this process with a script and cron is essential for reliable, regular protection. You also understand the critical components (db.sqlite, data/, config.php, plugins/) that need to be included. Remember the importance of storing backups offsite and testing your restore procedure.

8. Troubleshooting Common Issues

Even with careful setup, issues can arise during installation, configuration, or regular use of Kanboard. This section provides guidance on diagnosing and resolving common problems. The key is often methodical investigation and consulting log files.

General Troubleshooting Approach

1. Identify the Symptom: What exactly is happening? (e.g., Blank page, 500 Internal Server Error, login failure, feature not working, slow performance). When did it start? Was anything changed recently (update, config change, plugin install)?
2. Check the Logs: This is usually the most crucial step.
   • Kanboard Debug Log: If enabled (define('DEBUG', true); in config.php - use only for temporary debugging, not production!), detailed logs might appear in the data/debug.log file.
   • Web Server Error Log:
     • Apache: /var/log/apache2/error.log (or specific virtual host log).
     • Nginx: /var/log/nginx/error.log.
     • These logs capture errors related to web server configuration, PHP processing failures (like fatal errors, crashes), and file permission issues encountered by the server.
   • PHP Error Log: The location is defined in php.ini (error_log directive). Often /var/log/php/error.log, /var/log/phpX.Y-fpm.log, or sometimes within the web server log itself if not specified separately. Captures PHP warnings, notices, and errors that don't crash the whole process but indicate problems in the code.
   • Browser Developer Console: Press F12 in your browser. Check the "Console" tab for JavaScript errors and the "Network" tab for failed HTTP requests (e.g., 404 Not Found for assets, 500 errors for API calls).
3. Check File Permissions: Incorrect ownership or permissions are a very common cause of issues, especially after manual installations, restores, or updates. Ensure the web server user (www-data, apache, nginx) owns the Kanboard files and has necessary write permissions, particularly for the data directory and its subdirectories (data/files, data/cache, etc.) and potentially plugins. Use ls -l to check ownership and chmod/chown to fix (refer back to installation/restore steps for correct permissions).
4. Check Configuration:
   • config.php: Double-check database credentials, application URL, mail settings, plugin-specific configs. A typo here can break major functionality.
   • Web Server Configuration (httpd.conf, .htaccess, Nginx server block): Ensure AllowOverride All (Apache) is set if using .htaccess for routing. Check PHP handler configuration. Verify rewrite rules.
   • php.ini: Ensure all required PHP extensions are enabled. Check memory_limit, upload_max_filesize, post_max_size if dealing with large uploads or memory issues.
5. Check Prerequisites: Is the correct PHP version running? Are all required PHP extensions installed and enabled? Is the database server running and accessible?
6. Plugin Issues: If the problem started after installing/updating a plugin, try disabling it (remove its folder from the plugins directory) and see if the issue resolves. Plugin conflicts or bugs are common.
7. Browser Issues: Clear your browser cache and cookies. Try accessing Kanboard from a different browser or incognito/private window to rule out browser-specific problems or corrupted cache.
8. Server Resources: Check server load (top, htop), memory usage (free -h), and disk space (df -h). Running out of RAM, CPU, or disk space can cause various errors and performance issues.
9. Search Online: Copy specific, unique error messages from logs and search online (e.g., Kanboard GitHub Issues, forums, Stack Overflow). Others may have encountered the same problem.

Specific Common Issues and Solutions

• Blank White Page / HTTP 500 Internal Server Error:

  • Cause: Often a fatal PHP error.
  • Troubleshooting:
    1. Check PHP Error Log: This is the primary place to look. The log will usually contain the specific file, line number, and error message causing the failure.
    2. Check Web Server Error Log: May also contain related PHP error messages or indicate configuration problems.
    3. Enable Debug Mode (Temporarily): Set define('DEBUG', true); in config.php. This might display the error directly on the page (disable immediately after diagnosing).
    4. Permissions: Incorrect permissions on core files or the data directory can sometimes trigger this.
    5. .htaccess Issues (Apache): Syntax errors in .htaccess or AllowOverride not enabled.
    6. PHP Memory Limit: A complex operation might exceed memory_limit set in php.ini.
    7. Incomplete Update/Install: Missing files can cause fatal errors.

• Login Issues ("Bad username or password", Page Reloads):

  • Cause: Incorrect credentials, session problems, authentication backend issues, brute-force protection.
  • Troubleshooting:
    1. Verify Credentials: Double-check username and password (case-sensitive).
    2. Default Credentials: Try admin/admin if you suspect the admin password wasn't changed or was reset.
    3. Password Reset: Use the "Password reset" feature (requires email to be configured and working).
    4. Check Logs: Look for specific authentication errors in Kanboard debug logs or web server logs.
    5. Session Issues: Ensure the web server has write permissions to PHP's session save path (defined in php.ini). Check disk space. Clear browser cookies for the Kanboard site. Check session.cookie_secure and session.cookie_httponly settings in php.ini vs. your HTTPS setup.
    6. Brute-Force Lockout: Check Kanboard settings (or logs) if brute-force protection is enabled and you might be locked out. Wait for the lockout period or check the database (remember_me table or similar, depending on version/implementation) if you need to unlock manually (use with caution).
    7. LDAP/Reverse Proxy Auth: If using external authentication, troubleshoot the connection to the LDAP server or the reverse proxy configuration. Check relevant logs on those systems.

• File Upload Failures:

  • Cause: Permissions, PHP limits, web server limits.
  • Troubleshooting:
    1. Permissions: Ensure the data/files directory exists and is writable by the web server user (www-data). Check permissions recursively.
    2. PHP Configuration (php.ini): Check upload_max_filesize (max size for a single file) and post_max_size (max size of the entire POST request body, must be >= upload_max_filesize). Restart PHP-FPM or the web server after changes.
    3. Web Server Configuration: Some web servers (like Nginx) might have their own client body size limits (e.g., client_max_body_size in Nginx config) that also need adjusting.
    4. Disk Space: Ensure the server partition hosting the data directory has enough free space.
    5. Check Logs: Look for specific errors related to file uploads or permissions in PHP/web server logs.

• CSS/JS Not Loading (Broken Layout):

  • Cause: Incorrect Application URL, web server rewrite/alias issues, permission problems on asset files, browser cache.
  • Troubleshooting:
    1. Check Application URL: Ensure define('KANBOARD_URL', 'https://your.kanboard.domain.com'); (or the equivalent setting) in config.php or Application Settings is correct and matches how you access the site.
    2. Browser Developer Console (Network Tab): Check for 404 errors when loading CSS or JS files. Note the paths that are failing.
    3. Web Server Configuration: If using aliases or complex rewrite rules, ensure they correctly map URLs like /assets/... to the physical assets directory in your Kanboard installation. For Apache, ensure mod_rewrite is enabled and .htaccess is processed (AllowOverride All).
    4. Permissions: Verify that the web server user has read access to the assets directory and the files within it.
    5. Clear Browser Cache: Force-refresh (Ctrl+Shift+R or Cmd+Shift+R) or clear the cache completely.

• Slow Performance:

  • Cause: Server resource exhaustion, database issues, complex filters, numerous plugins, network latency.
  • Troubleshooting:
    1. Monitor Server Resources: Use top or htop to check CPU usage (is php or mysqld high?). Use free -h to check RAM usage and swap. Use df -h for disk space. Use iotop (if installed) to check disk I/O.
    2. Database Performance: If using MySQL/PostgreSQL, use database-specific tools to check for slow queries (SHOW PROCESSLIST; in MySQL, enable slow query logging). Consider tuning database configuration (e.g., buffer pool size). Run database maintenance (OPTIMIZE TABLE, VACUUM). If using SQLite on a very busy instance, consider migrating to MySQL/Postgres.
    3. Kanboard Analytics/Reports: Some complex analytics might be slow on large datasets.
    4. Plugins: Too many plugins, or a poorly written plugin, can impact performance. Try disabling plugins one by one to identify offenders.
    5. Network: Check network latency between the client and server if access feels sluggish.
    6. PHP Version: Ensure you are using a recent, supported PHP version, as newer versions often bring performance improvements. Check if using an opcode cache like OPCache (usually enabled by default) is active and configured optimally.
    7. Number of Tasks/Projects: Very large numbers of tasks on a single board or extremely complex filters can slow down board rendering.

• Plugin Installation/Update Failures:

  • Cause: Permissions, PHP zip extension missing, network issues (for UI install), incorrect folder structure.
  • Troubleshooting:
    1. Permissions: Ensure the plugins directory is writable by the web server user (www-data) during installation/update via UI. Ensure extracted plugin files have correct read permissions afterward.
    2. PHP Zip Extension: The UI installer requires the php-zip extension. Install it (sudo apt install phpX.Y-zip) and restart the web server/PHP-FPM.
    3. Network Issues: If installing via UI fails to download, check the server's internet connectivity and DNS resolution. Firewalls might block outgoing connections.
    4. Manual Install Folder Structure: When installing manually, ensure the plugin files (Plugin.php, etc.) are directly inside the plugins/PluginName directory, not nested further (e.g., NOT plugins/PluginName-1.0/PluginName/Plugin.php).
    5. Check Logs: Look for errors during the installation attempt in web server/PHP logs.

Workshop Debugging a Simulated Problem

Let's simulate a common issue – a broken layout due to an incorrect Application URL – and walk through debugging it.

• Objective: To diagnose and fix a broken Kanboard layout by checking logs, browser console, and configuration.
• Scenario: After migrating the Kanboard server or changing its domain name, users report that the Kanboard page loads but looks broken (no styling, potentially missing icons or images).

• Prerequisites:

  • Working Kanboard installation.
  • Access to Kanboard via browser.
  • sudo access to the server via SSH.
  • Ability to edit config.php or Application Settings in Kanboard UI.

• Steps:

  1. Simulate the Problem:

     • Log in to Kanboard as admin.
     • Go to Settings -> Application Settings.
     • Change the Application URL to something incorrect, e.g., prepend http:// if you are using https://, or change the domain slightly (e.g., https://kanboard.wrongdomain.com).
     • Click "Save".
     • Immediately refresh the page (or navigate to the dashboard). The layout will likely break. You might see plain text, links, but no proper styling.

  2. Observe the Symptom:

     • Confirm the broken layout. Note that basic HTML content might be present, but CSS and possibly JavaScript are not applied correctly.

  3. Check Browser Developer Console:

     • Press F12 in your browser to open Developer Tools.
     • Go to the "Console" tab. Look for errors like Failed to load resource: net::ERR_NAME_NOT_RESOLVED or similar, indicating the browser couldn't load files. Note the URLs it's trying to load – they will likely contain the incorrect domain you just entered.
     • Go to the "Network" tab. Refresh the page (F5 or Ctrl+R). Filter by "CSS" or "JS". You will likely see requests for CSS/JS files failing (e.g., status 404 Not Found, or DNS errors) because they point to the wrong URL.

  4. Check Logs (Less Likely Helpful Here, but Good Practice):

     • In this specific case (incorrect URL causing client-side loading failures), server-side logs (Apache/Nginx error log, PHP error log) are unlikely to show errors unless the incorrect URL caused secondary problems. However, it's always good practice to check them briefly for any unusual activity.
     • bash sudo tail -n 50 /var/log/apache2/error.log sudo tail -n 50 /var/log/php/error.log # Adjust path if needed

  5. Formulate Hypothesis: Based on the browser console errors showing attempts to load assets from the wrong domain, the most likely cause is the incorrect "Application URL" setting in Kanboard. This setting is used by Kanboard to generate the URLs for its assets (CSS, JS, images).

  6. Verify and Fix Configuration:

     • Since the UI might be hard to use with a broken layout, editing config.php directly is often easier.
     • Connect via SSH:

       ssh your_username@your_server_ip
       sudo nano /var/www/html/kanboard/config.php # Adjust path
       

     • Look for the KANBOARD_URL definition or comment related to the application URL.

       // Website URL (must be defined if not detected automatically)
       // define('KANBOARD_URL', 'https://kanboard.wrongdomain.com'); // <-- Found the wrong URL
       

     • Correct the URL to the actual, working address:

       define('KANBOARD_URL', 'https://your.correct.domain.com'); // <-- Corrected URL
       

       • Note: If the line is commented out (//) or missing, Kanboard tries to auto-detect. In some setups, explicitly defining it is more reliable. If you changed it via the UI, this line might not be in config.php but rather stored in the database. If direct config edit doesn't fix it, you might need to fix it in the DB (advanced) or try navigating the broken UI back to Settings -> Application Settings if possible. For this workshop, assume config.php edit works or you can navigate the UI.
     • Save the file (Ctrl+O, Enter) and Exit (Ctrl+X).

  7. Test the Fix:

     • Go back to your browser.
     • Clear cache and perform a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).
     • The Kanboard page should now load with the correct styling and layout.
     • Check the Developer Console again – the CSS/JS files should now load successfully (Status 200 OK).

• Reflection: This workshop demonstrated a common troubleshooting scenario. By observing the symptom (broken layout), using the browser's developer tools (Console/Network tabs) to pinpoint the root cause (failed asset loading due to wrong URLs), and correcting the relevant configuration (Application URL), you were able to resolve the issue systematically. This highlights the importance of checking client-side errors and configuration settings.

Conclusion

Congratulations! You have journeyed through the process of setting up, configuring, customizing, managing, securing, and troubleshooting your own self-hosted Kanboard instance. Starting from the basic prerequisites and installation, you progressed through user management, workflow customization with columns, categories, and plugins, and delved into advanced topics like HTTPS, email configuration, backups, and updates.

By following the verbose explanations and completing the hands-on workshops, you should now possess a solid understanding of:

• The components required for self-hosting web applications like Kanboard (OS, web server, PHP, database).
• Manual installation procedures and the importance of file permissions.
• Navigating and utilizing Kanboard's core features: projects, boards, columns, swimlanes, tasks, subtasks, comments, and attachments.
• Managing users, groups, and permissions for collaborative projects.
• Tailoring Kanboard through application/project settings and extending its functionality with plugins.
• Implementing essential security measures like HTTPS.
• Configuring integrations like SMTP for email notifications.
• Establishing robust backup and restore procedures.
• Safely performing Kanboard updates.
• Systematically troubleshooting common issues using logs and browser tools.

Self-hosting Kanboard empowers you with full control over your project management data and environment. It provides a flexible, private, and often cost-effective alternative to cloud services. The skills you've developed here – server administration basics, application configuration, troubleshooting techniques – are transferable and valuable in many technical fields.

The journey doesn't end here. Continue exploring Kanboard's features, browse the plugin directory for more extensions, investigate advanced integrations using the API or webhooks, and perhaps even contribute to the Kanboard open-source project or its plugin ecosystem. Consult the official Kanboard documentation and community forums for further learning and support.

You are now well-equipped to manage your projects efficiently and effectively using your own powerful, self-hosted Kanboard instance.