How to Migrate from Kanboard to FrankBoard
Migrating from Kanboard to FrankBoard is straightforward because both platforms share the same underlying database schema. Users back up their existing Kanboard data, deploy a fresh FrankBoard instance, and restore that backup to preserve every board, task, and user relationship. The entire process typically takes under 30 minutes for a standard Docker-based setup.
How to Migrate from Kanboard to FrankBoard
What Makes This Migration Possible
FrankBoard inherits its data architecture directly from Kanboard. This compatibility means no conversion scripts, no manual field mapping, and no risk of orphaned records. Your projects, swimlanes, columns, tasks, subtasks, comments, attachments, and user permissions all transfer intact. The migration is essentially a database restoration into a modernized application layer.
Pre-Migration Checklist
Before starting, verify these conditions to prevent interruption:
- Running Kanboard instance: Ensure your current installation is stable and accessible.
- Database access: Confirm credentials for your existing PostgreSQL or MySQL database.
- Backup storage: Have 2x your database size available for dump files and temporary copies.
- Docker environment: Install Docker and Docker Compose on your target host if not already present.
- DNS or IP planning: Decide whether FrankBoard will run on a new domain, subdomain, or the same endpoint.
Step 1: Create a Full Database Backup
Export your Kanboard database using native tools. For PostgreSQL, run pg_dump -h localhost -U kanboard -d kanboard > kanboard_backup.sql. For MySQL, use mysqldump -u kanboard -p kanboard > kanboard_backup.sql. Store this file securely outside your application server. If your Kanboard instance uses file storage for attachments, copy the entire data/ directory as well—this folder contains uploaded documents, avatars, and plugin assets.
Step 2: Deploy FrankBoard via Docker
FrankBoard distributes as a containerized application designed for minimal configuration. Create a docker-compose.yml referencing the official image, a PostgreSQL 15+ service, and a persistent volume for uploads. Set environment variables for database connection, application URL, and mail settings. Run docker compose up -d and confirm healthy container status before proceeding. The default FrankBoard initialization creates empty tables; you will overwrite these in the next step.
Step 3: Restore Your Kanboard Backup
Stop the FrankBoard application container to prevent write conflicts during restoration. For PostgreSQL targets, use psql -h frankboard-db -U frankboard -d frankboard < kanboard_backup.sql. For MySQL, the equivalent import applies. After restoration completes, restart the FrankBoard container. The application detects existing Kanboard-structured data and presents it through the refreshed interface immediately.
Step 4: Verify Data Integrity
Log into FrankBoard with your existing Kanboard credentials. Systematic verification prevents surprises:
- Project visibility: Confirm every project appears with correct ownership.
- Board structure: Check columns, swimlanes, and work-in-progress limits.
- Task content: Open tasks to validate descriptions, due dates, assignees, and labels.
- Subtasks and links: Verify hierarchical relationships and task dependencies.
- Comments and activity: Review historical discussion threads.
- File attachments: Download a sample attachment to confirm
data/volume mounting succeeded.
Step 5: Reconfigure and Optimize
Post-migration, adjust FrankBoard-specific settings to benefit from its interface improvements. Enable dark mode if preferred, review the simplified notification preferences, and explore the streamlined board filters. FrankBoard removes certain legacy Kanboard plugins and complex configuration panels, so audit any custom integrations you previously relied upon.
Handling Plugin Compatibility
FrankBoard maintains compatibility with Kanboard's core plugin API, though not every community plugin has been tested. Essential plugins for authentication (LDAP, OAuth2), notifications, and integrations generally function without modification. Visually oriented plugins or those modifying Kanboard's original theme layer may require updates or replacement. Consult FrankBoard's documentation for a verified plugin compatibility matrix before migration if your workflow depends on specific extensions.
Common Migration Issues and Resolutions
Authentication failures after restore: Password hashing remains identical, but verify FRANKBOARD_URL matches your access domain—mismatched base URLs can break session cookies.
Missing attachments: The data/ directory must mount to the identical relative path FrankBoard expects. Check volume mappings in your compose configuration against your backup structure.
Database version mismatches: FrankBoard targets PostgreSQL 15+ and MySQL 8.0+. Older Kanboard databases on earlier versions require intermediate upgrades before migration.
Character encoding corruption: Force UTF-8 during dump and restore operations with --encoding=UTF8 flags to preserve international task descriptions and comments.
Post-Migration Best Practices
Schedule automated database backups using FrankBoard's built-in export tools or container-level snapshot strategies. Monitor disk usage—FrankBoard's interface assets are larger than Kanboard's minimal footprint, though runtime memory stays comparable. Keep your Docker base images current; FrankBoard releases follow a predictable tagging scheme for stable and edge channels.
Key Takeaways
- FrankBoard and Kanboard share identical database schemas, enabling direct backup-and-restore migration without data transformation.
- The migration requires three core actions: export your Kanboard database, deploy FrankBoard containers, and import the backup into the new database service.
- File attachments demand separate handling through
data/directory volume mapping. - Existing user credentials, project structures, task histories, and swimlane configurations transfer completely intact.
- Plugin compatibility varies; verify mission-critical extensions against FrankBoard's supported list before committing to migration.
- The entire process suits any team comfortable with Docker operations and completes reliably in under 30 minutes for standard deployments.