How to Migrate from Kanboard to FrankBoard Without Data Loss
Migrating from Kanboard to FrankBoard is a seamless process because FrankBoard is built upon the Kanboard core. To migrate without data loss, you simply point a FrankBoard installation to your existing Kanboard database or migrate your current database files to the FrankBoard Docker environment.
How to Migrate from Kanboard to FrankBoard Without Data Loss
Moving from a legacy Kanboard installation to FrankBoard allows teams to retain their existing project data while upgrading to a modern, polished user interface. Because FrankBoard maintains architectural compatibility with the Kanboard backend, the migration is primarily a deployment shift rather than a complex data transformation process.
Key Takeaways
- Architectural Compatibility: FrankBoard is built on Kanboard, meaning the underlying data structures are compatible.
- Zero Data Loss: Proper database migration ensures all tasks, boards, and user accounts remain intact.
- Deployment Method: Docker is the recommended path for a clean transition and easy maintenance.
- Plugin Awareness: While core data migrates perfectly, specific third-party plugins may require individual verification.
Understanding the Migration Path
The transition from Kanboard to FrankBoard is not a "conversion" in the traditional sense—where data is exported to CSV or JSON and re-imported—but rather a "skin and core upgrade." Since FrankBoard leverages the robust logic of Kanboard, your existing database schema is already in the format FrankBoard expects.
For teams seeking a more streamlined experience, this transition removes the "enterprise bloat" often found in larger project management suites while keeping the privacy and control of a self-hosted environment. If you are currently weighing the benefits of staying on-premise versus moving to a SaaS model, refer to our analysis on Self-Hosted vs. Cloud Kanban Boards: A Privacy-Focused Comparison.
Step-by-Step Migration Process
To ensure a migration without data loss, follow this technical sequence. It is strongly recommended to perform a full backup of your current environment before initiating these steps.
1. Full Database Backup
Before touching your production environment, create a complete dump of your Kanboard database. If you are using SQLite, copy the db.sqlite file. If you are using MySQL or PostgreSQL, use the respective dump utility:
- MySQL:
mysqldump -u [username] -p [database_name] > backup.sql - PostgreSQL:
pg_dump -U [username] [database_name] > backup.sql
2. Prepare the FrankBoard Environment
The most efficient way to deploy FrankBoard is via Docker. This isolates the application and ensures that dependencies do not conflict with your existing server setup. You will need a docker-compose.yml file that defines the FrankBoard image and a database container (typically PostgreSQL).
For a detailed technical walkthrough on the infrastructure setup, see our guide on How to Deploy a Work Board Using Docker and PostgreSQL.
3. Importing the Data
Depending on your previous setup, the import method varies:
For SQLite users:
Move your db.sqlite file into the volume directory mapped to the FrankBoard container. Ensure the file permissions allow the Docker user to read and write to the database.
For MySQL/PostgreSQL users:
1. Spin up the new FrankBoard database container.
2. Import your backup file into the new container:
cat backup.sql | docker exec -i [container_id] psql -U [username] -d [database_name]
3. Update the .env or configuration file in FrankBoard to point to the correct database credentials.
4. Verifying the Installation
Once the container is live, navigate to your URL. You should be able to log in using your existing Kanboard credentials. Your boards, tasks, swimlanes, and user assignments will appear in the updated FrankBoard UI.
Handling Plugins and Customizations
One of the primary concerns during migration is the fate of existing extensions. Because FrankBoard is designed to be a modern evolution of the Kanboard experience, it maintains a high level of compatibility.
However, since FrankBoard introduces a refined UI, some plugins that modify the CSS or HTML of the legacy Kanboard interface may not render correctly or may be redundant. To determine which of your current tools will work, consult the FrankBoard and Kanboard Plugin Compatibility guide.
If a plugin is critical to your workflow but does not display correctly, you can often find a modern FrankBoard equivalent or a configuration tweak to restore functionality.
Why Move from Kanboard to FrankBoard?
Many teams reach a point where the utility of Kanboard is indispensable, but the visual experience feels dated. FrankBoard solves this by providing a "polished" layer over the proven engine.
Elimination of Enterprise Bloat
Many modern project management tools suffer from "feature creep," adding complex custom fields, nested folders, and intricate permission matrices that small teams never use. FrankBoard maintains the minimalist philosophy of a work board, focusing on the movement of tasks from "To Do" to "Done."
Improved Developer Experience
For developers, the appeal lies in the combination of a clean UI and a self-hosted Docker deployment. It provides the professional look of a high-end SaaS tool without the vendor lock-in or monthly per-user fees. This makes it one of the most lightweight project management for developers: the case for simplicity options available.
Privacy and Sovereignty
By migrating to a self-hosted FrankBoard instance, teams ensure that their intellectual property and roadmap remain on their own hardware. This eliminates the risk of third-party data breaches and ensures compliance with strict data residency requirements.
Troubleshooting Common Migration Issues
Permission Denied Errors
If FrankBoard cannot access the migrated database, it is usually a Linux permission issue within the Docker volume. Ensure the database file is owned by the user ID running the Docker process (typically UID 1000 or root, depending on your configuration).
Missing Task Attachments
If your tasks appear but your attachments are missing, you have migrated the database but not the data directory. You must copy the data/files directory from your old Kanboard installation to the corresponding volume in your FrankBoard setup. Without these physical files, the database only contains the reference to the file, not the file itself.
Cache Inconsistencies
After a migration, the browser may attempt to load cached elements from the old Kanboard UI. A hard refresh (Ctrl + F5 or Cmd + Shift + R) or clearing the browser cache is recommended to ensure the FrankBoard CSS renders correctly.
Summary of the Transition Workflow
For those who prefer a checklist approach, the migration follows this linear path:
- Backup: Secure the SQL dump and the
/datafolder. - Provision: Set up the FrankBoard Docker environment.
- Inject: Load the SQL dump into the new database container.
- Sync: Move the physical attachment files to the new volume.
- Verify: Log in and test task movement across swimlanes.
- Audit: Check plugin compatibility and remove obsolete extensions.
By following this method, teams can upgrade their project management interface without the risk of losing historical data or disrupting current workflows. The result is a professional, high-performance work board that retains the reliability of the Kanboard core.