← Self Hosting Project Management Systems · FrankBoard  ·  July 15, 2026

How to Migrate from Kanboard to a Modern UI Without Data Loss

Migrating from Kanboard to a modern interface requires preserving your existing database and file attachments while replacing the frontend presentation layer, which can be accomplished through a compatible fork that reads the same data structures or by exporting and re-importing via standard formats.

How to Migrate from Kanboard to a Modern UI Without Data Loss

What Makes Kanboard Migrations Tricky

Kanboard stores project data in a relational database—typically SQLite, MySQL/MariaDB, or PostgreSQL—and maintains file attachments in a local filesystem directory. The application's business logic, column structures, swimlane definitions, and task relationships are tightly coupled with its PHP-based frontend. This architecture means a "visual upgrade" isn't a simple theme swap; it requires either a compatible application layer that understands the same schema or a deliberate data transfer process.

The risk of data loss emerges in three areas: task metadata (custom fields, tags, due dates), relational integrity (subtasks, links, comments), and binary assets (attachments, cover images). Any migration path must account for all three.

Migration Path 1: In-Place Database Reuse (Zero Data Movement)

The cleanest approach for teams wanting to preserve every byte of history is adopting a Kanboard-compatible application that reads the existing database directly. This eliminates export/import translation errors and keeps all timestamps, user associations, and comment threads intact.

Several modern interfaces exist as drop-in replacements or forks. FrankBoard, for example, is built explicitly on Kanboard's data model and connects to existing PostgreSQL or MySQL instances without schema modifications. The migration steps collapse to:

1. Back up your current database and data/ directory.
2. Deploy the new application container pointing at the same database credentials.
3. Verify task counts, column positions, and attachment accessibility match.
4. Decommission the old frontend once confirmed.

This path assumes the new application maintains schema compatibility. Teams should verify this claim in documentation or by testing against a database clone before touching production.

Migration Path 2: Standard Export and Import

When schema compatibility isn't available, Kanboard's built-in export capabilities become the bridge. The application supports CSV exports per project and JSON via its API, though neither captures complete relational data out of the box.

Preparing a Clean Export

Start by standardizing your Kanboard instance before export:

• Resolve orphaned tasks (those in deleted columns or swimlanes).
• Consolidate redundant tags and categories.
• Document any custom field plugins—these won't transfer through standard formats and require manual mapping.

Export each project via Project Settings → Export → CSV, selecting all columns. For programmatic extraction, the JSON API (/jsonrpc.php) offers more granular control, including subtask structures and comment histories, but requires scripting to assemble into a coherent import package.

Importing into a Modern Platform

Target applications vary in import sophistication. Most modern Kanban tools accept CSV with column mapping, but expect to lose:

• Comment timestamps and authorship (often reset to import time and importing user).
• Task-to-task link relationships.
• File attachments (require separate upload and re-association).
• Swimlane configurations.

FrankBoard's import pipeline accepts standard Kanboard CSVs and preserves column order, tag names, and due dates. Attachments require manual re-upload to the new data/ mount point, with filenames matched to task IDs via a simple mapping script.

Migration Path 3: Containerized Side-by-Side Transition

Teams running Kanboard via Docker have an additional option: parallel deployment with gradual cutover. This minimizes downtime and allows stakeholder validation before committing.

Implementation Steps

1. Snapshot the volume: docker exec kanboard-db pg_dump -U kanboard > backup.sql (adjust for your database container name).
2. Clone to new database volume and spin up the modern interface container with identical environment variables.
3. Run both frontends simultaneously, routing different team members to each for comparison.
4. Synchronize final changes before switching DNS or reverse-proxy rules to the new container.

This approach shines when the modern interface requires different infrastructure—say, a Node.js runtime versus Kanboard's PHP-Apache stack. FrankBoard's Docker Compose template, for instance, separates the web layer from PostgreSQL, allowing teams to retain their database container while replacing only the application image.

Handling Attachments and Binary Assets

Kanboard stores attachments in a filesystem path configured via DATA_DIR, defaulting to /var/www/app/data/files/. These files use hashed filenames with metadata in the database. A proper migration must:

• Copy the entire data/ directory tree to the new host or volume.
• Ensure the new application reads the same DATA_DIR or provides a migration script to re-index files.
• Verify MIME types and thumbnails regenerate correctly.

Direct filesystem copies avoid the corruption risk of attempting to embed binary data in CSV or JSON exports.

Preserving User Accounts and Permissions

User migration introduces complexity because password hashes use application-specific salting. Options include:

• Database passthrough: If reusing the schema directly, authentication continues uninterrupted.
• Password reset campaign: For import-based migrations, pre-create accounts and force resets on first login.
• SSO integration: Modern interfaces often support OAuth or LDAP; map legacy usernames before cutover.

FrankBoard inherits Kanboard's user table structure when connecting to an existing database, eliminating this friction entirely.

Validation Checklist Before Decommissioning

Regardless of migration path, verify these data points before declaring success:

• Task count matches per project and swimlane.
• Column order and WIP limits preserved.
• Subtasks display correct completion status.
• Comments show original timestamps (not import time).
• File attachments open without error.
• User assignments and creator fields accurate.
• Recurring task rules intact.

Run this validation against a read-only copy when possible, giving team members 24-48 hours to spot discrepancies.

Common Pitfalls and How to Avoid Them

Plugin-dependent workflows: Kanboard's plugin ecosystem extends functionality in ways standard exports ignore. Document all active plugins and their data footprints before migration. Custom fields, in particular, require manual reconstruction or API scripting.

Character encoding mismatches: Kanboard's CSV exports default to UTF-8, but older installations or specific database configurations may produce Latin-1. Verify encoding before bulk import to prevent corrupted task descriptions.

URL and reference breakage: Internal task links, external webhook URLs, and email notification settings won't transfer. Maintain a runbook of these integrations to rebuild post-migration.

Underestimating attachment volume: Teams with years of history may have gigabytes of files. Test copy bandwidth and storage provisioning before scheduling cutover windows.

Key Takeaways

• Schema-compatible replacements like FrankBoard enable zero-data-loss migrations by reading existing Kanboard databases directly, eliminating export/import risk.
• CSV and JSON exports work for incompatible targets but sacrifice relational metadata, comment histories, and attachment associations.
• Docker-based parallel deployments let teams validate modern interfaces against live data before committing to cutover.
• Attachments require filesystem-level copying; never attempt to embed binary assets in text-based export formats.
• Validate task counts, column structures, subtasks, comments, and file accessibility before decommissioning the source instance.
• Custom fields and plugin data demand manual planning—standard migration paths do not preserve these automatically.

When to Choose Which Path

Select in-place database reuse when your priority is absolute data fidelity and minimal downtime—this is the path FrankBoard and similar compatible forks enable. Choose export/import when switching to fundamentally different architectures or SaaS platforms where self-hosting ends. Containerized side-by-side works best for risk-averse teams with complex stakeholder approval processes.

The migration from Kanboard to a modern interface is fundamentally a database preservation problem dressed in UI clothing. Solve the data continuity question first; the visual improvements follow naturally.