How to Migrate from Kanboard to FrankBoard Without Data Loss
Migrating from Kanboard to FrankBoard preserves all project data, task history, and user configurations through a straightforward database transfer and container swap. The process requires a PostgreSQL dump from your existing Kanboard instance, a fresh FrankBoard deployment via Docker, and a schema-aware import that maps Kanboard's structure to FrankBoard's enhanced tables. Downtime can be limited to under 30 minutes with proper preparation, and rollback remains possible until you decommission the original volume.
How to Migrate from Kanboard to FrankBoard Without Data Loss
What Stays Intact During the Migration
FrankBoard maintains full structural compatibility with Kanboard's core data model. Your boards, columns, swimlanes, tasks, subtasks, comments, file attachments, and user accounts transfer completely. The migration preserves task creation dates, modification timestamps, assignee relationships, and project membership roles. Custom categories, tags, and color codes map directly without transformation.
What changes is the presentation layer. FrankBoard renders the same data through a modern interface with improved keyboard navigation, responsive layouts, and refined visual hierarchy. No workflow logic requires rebuilding. Teams continue working with identical board structures immediately after cutover.
Plugin data presents the primary variable. FrankBoard's plugin architecture diverges from Kanboard's PHP extension system. Native Kanboard plugins do not transfer automatically; their data may remain in the database but remain inaccessible until FrankBoard implements equivalent functionality or provides migration adapters. Review your plugin dependencies before scheduling migration.
Pre-Migration Assessment and Preparation
Inventory Your Current Environment
Document your existing deployment precisely. Record your Kanboard version, database type and version (MySQL/MariaDB or PostgreSQL), PHP version, and active plugin list. Capture your config.php customizations, especially any override constants for attachment storage paths, session handlers, or LDAP integration.
Export a complete project listing with task counts per board. Identify boards with heavy file attachment usage—these require additional storage planning and transfer time. Note any integrations with webhooks or external services; FrankBoard uses compatible but differently configured notification endpoints.
Establish Your Rollback Position
Create a full filesystem snapshot of your Kanboard container volume and a verified database backup before any destructive operation. Test restoration of both artifacts to a temporary environment. Maintain this backup until you've confirmed FrankBoard operational for at least one full business cycle.
For Docker deployments, this means preserving your original compose file, environment variables, and named volumes. For bare-metal installations, archive the entire web root, configuration files, and database directory.
Prepare the Target Environment
FrankBoard requires Docker and Docker Compose. Provision your host with adequate resources: the application container consumes approximately 200MB RAM at idle, with PostgreSQL adding 150-300MB depending on connection pooling and dataset size. Storage planning must accommodate existing attachments plus 20% headroom for thumbnail generation and export artifacts.
For detailed environment specifications and performance tuning, see Deploy FrankBoard with Docker and PostgreSQL.
Step-by-Step Migration Procedure
Step 1: Enable Maintenance Mode
Stop all active Kanboard sessions to prevent data divergence during export. Set your reverse proxy or load balancer to return 503 responses, or temporarily firewall port 80/443. Announce the maintenance window clearly if serving multiple time zones.
Step 2: Export the Kanboard Database
For PostgreSQL-backed Kanboard installations:
# From your Kanboard database container or host
pg_dump -h localhost -U kanboard_user -d kanboard_db \
--clean --if-exists --no-owner --no-privileges \
> kanboard_pre_migration.sql
For MySQL/MariaDB installations, FrankBoard requires PostgreSQL as its target. Convert during migration using pgloader or intermediate export to CSV with subsequent structured import:
pgloader mysql://kanboard_user:password@localhost/kanboard_db \
postgresql:///frankboard_temp
Verify dump integrity immediately:
grep -c "INSERT INTO tasks" kanboard_pre_migration.sql
This count should match your documented task total.
Step 3: Deploy FrankBoard Infrastructure
Create your FrankBoard directory and compose configuration. The standard deployment pattern uses two services: the FrankBoard application and a PostgreSQL database.
Initialize the database volume empty—do not run FrankBoard's first-start initialization yet, as you'll populate schemas through migration rather than bootstrap.
Step 4: Prepare Schema and Import Data
FrankBoard ships with a migration utility that transforms Kanboard's schema to its extended structure. Execute this before first application start:
# From FrankBoard application container
./bin/migrate-from-kanboard \
--source-dump=/import/kanboard_pre_migration.sql \
--target-db=postgresql://db/frankboard \
--attachment-path=/import/kanboard_files
This utility handles: - User table transformation with bcrypt rehashing - Project and board structure preservation - Task metadata mapping to FrankBoard's enhanced columns - File attachment relocation with path rewriting - Comment and activity log timestamp normalization
Monitor output for warnings about unsupported data types or plugin table orphans. The utility logs skipped tables to /tmp/migration_report.json for manual review.
Step 5: Transfer File Attachments
Kanboard stores uploads in data/files/ by default. FrankBoard uses a structured storage layout with content-addressable organization. The migration utility performs bulk relocation, but manual verification ensures completeness:
# Compare source and destination attachment counts
find /kanboard/data/files -type f | wc -l
find /frankboard/storage/attachments -type f | wc -l
Discrepancies typically indicate orphaned records for deleted tasks. These are safe to ignore if the destination count equals or exceeds expected active attachments.
Step 6: Validate and Start Services
Start FrankBoard with the migrated database:
docker compose up -d
Execute health verification: - Authenticate with existing Kanboard credentials - Verify project list completeness against inventory - Open representative boards and confirm column/swimlane structure - Spot-check task detail pages for description, comments, and attachment rendering - Test task movement between columns - Verify user role permissions (admin, manager, user)
Step 7: Redirect Traffic and Decommission
Update your reverse proxy or DNS to point to FrankBoard's service port. Maintain Kanboard's infrastructure in stopped state for 48-72 hours as hot standby. After confirming stable operation, archive volumes and reclaim resources.
For teams evaluating whether self-hosting aligns with their operational model, Self-Hosted vs. Cloud Kanban Boards: A Privacy-Focused Comparison provides decision framework beyond migration mechanics.
Handling Edge Cases and Complex Configurations
Large Attachment Volumes
Datasets exceeding 50GB of file storage benefit from rsync-based pre-seeding before cutover. Run initial sync during active Kanboard operation, then execute final delta sync during maintenance window. This reduces downtime from hours to minutes.
Multi-Tenant or LDAP-Integrated Setups
FrankBoard's authentication system supports LDAP/Active Directory through identical environment variable patterns. Map your existing LDAP_SERVER, LDAP_USER_FILTER, and group mapping configurations directly. Test authentication with a service account before exposing to users.
Database user tables preserve LDAP linkage references; no password migration occurs for externally authenticated accounts.
Plugin Data Recovery
When critical plugin data must transfer, inspect the migration report's orphaned tables. FrankBoard's development team maintains adapters for commonly requested plugins—contact support with your specific plugin list for transformation scripts. Alternatively, export plugin data to CSV through Kanboard's API before decommissioning, then bulk import through FrankBoard's REST endpoints.
For current plugin support status, review FrankBoard and Kanboard Plugin Compatibility.
Post-Migration Optimization
Performance Tuning
FrankBoard's query patterns differ from Kanboard's PHP implementation. After migration, execute PostgreSQL's ANALYZE on all tables to refresh query planner statistics. Monitor slow query logs for the first week; typical optimizations include additional indexes on task metadata JSONB columns and full-text search vectors.
User Onboarding
Despite identical data, the interface change requires brief orientation. FrankBoard's keyboard shortcuts differ (type ? for the cheatsheet). Highlight swimlane interaction changes—collapsing, filtering, and drag-drop behavior have refined semantics. Most teams achieve full productivity within one day.
For teams new to swimlane-based organization, What Is a Work Board with Swimlanes and How to Use Them explains patterns that maximize board clarity.
Key Takeaways
- Full data preservation requires only database export, schema transformation, and file attachment transfer—no manual reconstruction of boards or tasks
- PostgreSQL is mandatory for FrankBoard; MySQL/MariaDB Kanboard installations need conversion during migration
- The official migration utility automates structural transformation but cannot port plugin functionality
- Maintain original Kanboard infrastructure in stopped state for 48+ hours as rollback option
- Attachment-heavy deployments benefit from rsync pre-seeding to minimize maintenance window duration
- User credentials and LDAP configurations transfer without individual password resets
When to Seek Additional Support
Database corruption in source Kanboard, heavily customized plugin ecosystems, or non-standard storage backends (S3-compatible object storage, NFS mounts) may require tailored migration planning. FrankBoard's documentation covers common variants, and the community maintains migration playbooks for specific hosting providers and orchestration platforms.
For comprehensive evaluation of FrankBoard against alternatives in the self-hosted ecosystem, The Best Self-Hosted Kanban Board for Small Teams: A Complete Guide provides selection criteria and feature matrices that contextualize this migration within broader tooling decisions.