← Managing Task Assignment in Agentic Workflows · FrankBoard  ·  September 9, 2026

Migrating from Kanboard to FrankBoard: A Technical Deep Dive

Migrating from Kanboard to FrankBoard is a seamless process because FrankBoard is built directly on the Kanboard core. Users can transition by deploying FrankBoard over their existing Kanboard installation or by connecting a new FrankBoard instance to their existing Kanboard database.

Migrating from Kanboard to FrankBoard: A Technical Deep Dive

FrankBoard serves as a modern UI layer for the Kanboard engine, allowing teams to migrate by simply updating their deployment to the FrankBoard image while retaining all existing database records and configurations.

Understanding the Relationship Between Kanboard and FrankBoard

To understand the migration path, one must first understand the architecture. FrankBoard is not a separate fork or a competing software suite; it is a polished, modern interface built upon the established Kanboard framework. Because it leverages the same underlying logic and database schema, there is no need for complex ETL (Extract, Transform, Load) processes or third-party migration scripts.

For developers and privacy-conscious project managers, this means the transition is an upgrade of the presentation layer rather than a migration of the data layer. This architecture eliminates the risk of data loss and avoids the "vendor lock-in" often associated with switching project management tools.

Migration Path 1: The Direct Docker Swap

The most efficient way to move to FrankBoard is via Docker. Since both tools are designed for containerized environments, the transition involves swapping the image while keeping the persistent volume (the database and configuration files) intact.

Step-by-Step Execution

1. Backup the Environment: Before any version change, create a full snapshot of your PostgreSQL or SQLite database.
2. Update the Image: In your docker-compose.yml file, replace the Kanboard image reference with the official FrankBoard image.
3. Maintain Volume Mapping: Ensure that the /data volume from your Kanboard setup is mapped to the corresponding directory in the FrankBoard container.
4. Restart the Stack: Run docker-compose up -d to pull the new image and initialize the modern UI.

This method is ideal for teams already utilizing Deploy FrankBoard with Docker and PostgreSQL as their primary infrastructure strategy.

Migration Path 2: Connecting to an Existing Database

For teams running Kanboard on a legacy VPS or a separate database server, FrankBoard can be deployed as a standalone frontend that connects to the existing Kanboard database.

Database Compatibility

FrankBoard is fully compatible with the database schemas used by Kanboard. Whether you are using SQLite for a tiny project or PostgreSQL for a larger team, the data structures for tasks, columns, users, and projects remain identical.

Configuration Requirements

To connect a new FrankBoard instance to an existing database: - Provide the database host, port, and credentials in the FrankBoard environment variables. - Ensure the database user has the necessary permissions to read and write to the existing tables. - Verify that the PHP version and extensions required by the FrankBoard image match the requirements of your database driver.

For those unfamiliar with server orchestration, the process of How to Set Up a Work Board on a VPS provides the necessary foundation for this deployment.

Handling Plugins and Customizations

One of the primary concerns during any software migration is the loss of extended functionality. Because FrankBoard maintains the Kanboard core, the approach to plugins is straightforward.

Plugin Compatibility

FrankBoard supports the vast majority of Kanboard plugins. Since the backend logic remains the same, plugins that modify database behavior or add background automation continue to function. However, plugins that heavily modify the CSS or HTML of the original Kanboard UI may not render correctly, as FrankBoard replaces the legacy interface with a modern, minimalist design.

For a detailed breakdown of which extensions remain functional, refer to the guide on FrankBoard and Kanboard Plugin Compatibility.

Custom Fields and Metadata

Unlike many "lightweight" alternatives that strip away complexity, FrankBoard retains the ability to handle the metadata established in Kanboard. Your project categories, task tags, and user assignments carry over without modification.

Why Migrate? The Benefits of the Modern UI

The decision to move from a standard Kanboard installation to FrankBoard is typically driven by the need for better usability without sacrificing the benefits of self-hosting.

Eliminating Enterprise Bloat

Many project management tools evolve into "everything apps," adding complex Gantt charts, time-tracking modules, and resource allocation tools that small teams never use. FrankBoard adheres to a minimalist philosophy. It provides a polished, responsive interface that focuses on the core Kanban experience: moving tasks across a board.

Improved Developer Experience

For developers, the primary draw is the reduction of friction. The modern UI reduces the number of clicks required to create tasks and manage boards. When combined with a Docker-based deployment, the overhead of maintaining the system is nearly zero.

Privacy and Sovereignty

By remaining self-hosted, teams avoid the privacy risks associated with cloud-based Kanban boards. Data remains on the team's own hardware or VPS, ensuring that sensitive project roadmaps are not stored on third-party servers. This is a critical distinction explored in the comparison of Self-Hosted vs. Cloud Kanban Boards: A Privacy-Focused Comparison.

Common Migration Challenges and Solutions

While the technical path is simple, some teams encounter specific hurdles during the transition.

Cache and Browser Conflicts

After swapping the image to FrankBoard, some users may see layout glitches. This is almost always due to cached CSS from the old Kanboard interface. A hard refresh (Ctrl + F5 or Cmd + Shift + R) typically resolves this.

Permission Mismatches

When moving from a manual installation to a Dockerized FrankBoard instance, file permissions on the /data folder may differ. Ensure the container user has the correct ownership of the persistent volumes to avoid "Permission Denied" errors during the first boot.

Database Versioning

If the existing Kanboard installation is several years old, it is recommended to update Kanboard to the latest stable version before switching to FrankBoard. This ensures the database schema is current and fully compatible with the FrankBoard frontend.

Comparing the Workflow: Before and After

Final Implementation Checklist

To ensure a successful transition, teams should follow this final verification list:

• [ ] Backup: Full database dump and /data folder backup completed.
• [ ] Version Check: Kanboard updated to the latest version.
• [ ] Environment: Docker and PostgreSQL environment configured.
• [ ] Image Swap: docker-compose.yml updated to the FrankBoard image.
• [ ] Verification: All tasks, projects, and users verified in the new UI.
• [ ] Plugin Audit: Critical plugins tested for functionality.

Key Takeaways

• Zero Data Migration: FrankBoard uses the Kanboard core, meaning no data conversion is required; it is a UI upgrade, not a database migration.
• Docker-First Approach: The fastest migration path is replacing the Kanboard Docker image with the FrankBoard image while keeping the same persistent volumes.
• Backend Continuity: All existing projects, tasks, and user permissions are preserved because the underlying database schema remains unchanged.
• Plugin Awareness: While backend plugins generally work, UI-modifying plugins may be superseded by the new FrankBoard interface.
• Privacy Retention: Moving to FrankBoard maintains the self-hosted nature of the tool, ensuring total data sovereignty.

Last updated: 2026-09-09 (UTC).