Skip to content
Klutch.sh Docs

Deploying a Kanboard App

Introduction

Kanboard is a lightweight, open-source project management tool built in PHP. Deploying Kanboard with a Dockerfile on Klutch.sh delivers reproducible builds, managed secrets, and persistent storage for uploads and SQLite/MySQL data—all managed from klutch.sh/app. This guide walks through installation, repository preparation, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for a stable Kanban workflow.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Kanboard code/config (GitHub is the only supported git source)
  • Docker familiarity and PHP 8.1+ knowledge
  • Database credentials (MySQL/MariaDB) or plan to use the built-in SQLite with persistence
  • Storage for attachments and data

For onboarding, see the Quick Start.

Architecture and ports

  • Kanboard serves HTTP; set the internal container port to 8080.
  • If using MySQL/MariaDB, run it as a separate Klutch.sh TCP app exposed on port 8000, connecting internally on 3306.
  • Persistent storage is required for /var/www/app/data (SQLite/database files) and /var/www/app/data/files (attachments).

Repository layout

kanboard/
├── data/                   # SQLite DB and attachments (mount as volume)
├── plugins/                # Custom plugins
├── config.php              # Do not commit secrets; use env vars
├── Dockerfile              # Must be at repo root for auto-detection
├── composer.json           # If using Composer for extensions
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Install dependencies and run locally before pushing to GitHub:

Terminal window
composer install --no-dev --optimize-autoloader || true
php -S 0.0.0.0:8080 -t .

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
php -S 0.0.0.0:8080 -t .

Make it executable with chmod +x start.sh.

Dockerfile for Kanboard (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM php:8.2-apache


RUN apt-get update && apt-get install -y \
    libpng-dev libjpeg-dev libfreetype6-dev libzip-dev libicu-dev libonig-dev libxml2-dev git unzip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install pdo_mysql pdo_sqlite gd intl zip opcache \
    && a2enmod rewrite \
    && rm -rf /var/lib/apt/lists/*


WORKDIR /var/www/html


COPY . /var/www/html


RUN chown -R www-data:www-data /var/www/html


ENV PORT=8080


EXPOSE 8080
CMD ["apache2-foreground"]

Notes:

  • Includes both pdo_mysql and pdo_sqlite to support MySQL/MariaDB or SQLite.
  • Keep /var/www/app/data writable and on a persistent volume.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=8080
  • DATABASE_DRIVER=mysql (or sqlite)
  • DATABASE_HOST=<db-host>
  • DATABASE_NAME=<db-name>
  • DATABASE_USER=<db-user>
  • DATABASE_PASSWORD=<db-password>
  • DATABASE_PORT=3306
  • LOG_DRIVER=syslog (optional)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader || true
  • NIXPACKS_START_CMD=php -S 0.0.0.0:8080 -t .
  • NIXPACKS_INSTALL_PKGS="php82 php82Extensions.pdo_mysql php82Extensions.pdo_sqlite php82Extensions.intl php82Extensions.gd php82Extensions.zip"

These keep Kanboard compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/www/html/data — required for SQLite DB or file storage and attachments.
  • /var/www/html/plugins — optional if you install plugins at runtime.

Ensure these paths are writable inside the container.

Deploy Kanboard on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Kanboard.
  3. Set the internal port to 8080.
  4. Add the environment variables above (database settings, log driver, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /var/www/html/data (and /var/www/html/plugins if used), selecting sizes that fit your attachments and plugins.
  6. Deploy. Your Kanboard instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For MySQL/MariaDB on Klutch.sh, create a separate TCP app, expose it on port 8000, and point DATABASE_HOST to that endpoint (internal port 3306).

Sample configuration snippet

Add settings to config.php using environment variables:

<?php
return [
    'database_driver'   => getenv('DATABASE_DRIVER'),
    'database_hostname' => getenv('DATABASE_HOST'),
    'database_name'     => getenv('DATABASE_NAME'),
    'database_username' => getenv('DATABASE_USER'),
    'database_password' => getenv('DATABASE_PASSWORD'),
    'database_port'     => getenv('DATABASE_PORT'),
];

Health checks and production tips

  • Use a reverse proxy health endpoint (e.g., /) to verify the app responds.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep image and extension versions pinned; update intentionally.
  • Monitor volume usage on /var/www/html/data and resize before it fills.
  • Back up your database and attachments regularly; do not rely on container filesystems for durability.

Kanboard on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8080 for the app (8000 externally for TCP databases), you can deliver dependable Kanban boards without extra YAML or workflow overhead.