How to Migrate from Kanboard to a Modern UI Without Data Loss
Migrating from Kanboard to a modern interface does not require rebuilding your workflow from scratch. FrankBoard maintains full database compatibility with Kanboard, which means existing projects, tasks, swimlanes, and user assignments transfer directly without export-import cycles or data transformation. A migration consists of pointing your existing PostgreSQL or MySQL database at a FrankBoard container, updating your Docker Compose configuration, and restarting the stack.
How to Migrate from Kanboard to a Modern UI Without Data Loss
Why Standard Kanboard Upgrades Fail to Modernize the Interface
Kanboard's architecture separates data storage from presentation logic, yet the default frontend has remained functionally unchanged for years. Teams seeking visual improvements often attempt theme installations or CSS overrides, then discover these surface-level modifications break with core updates and never address interaction patterns. The underlying PHP templates and JavaScript dependencies create a brittle customization environment where even minor visual changes require maintaining forked code.
A genuine modernization requires replacing the presentation layer while preserving the proven backend structures that teams rely on. This is precisely the architectural decision behind FrankBoard's development: the same robust task engine, now served through a contemporary React-based interface with responsive design, real-time updates, and accessible keyboard navigation.
Understanding Database Compatibility
FrankBoard uses Kanboard's exact relational schema for projects, tasks, users, columns, swimlanes, tags, comments, attachments, and activity streams. This is not a migration tool or converter—it is the same data structures queried through a different API layer.
What this means practically: your projects table, tasks table with their project_id foreign keys, users table with role assignments, and all junction tables for tags and subtasks remain untouched during transition. The migration is read-preserving; FrankBoard does not rewrite or restructure your data on first boot.
Key compatibility points:
- PostgreSQL and MySQL supported: Both Kanboard's primary production databases work without conversion scripts
- Plugin data preserved: Third-party plugin tables remain in your database; FrankBoard ignores tables it does not use rather than deleting them
- File attachments maintained: The
filestable references and physical file storage paths carry forward - User credentials functional: Password hashes using Kanboard's bcrypt implementation authenticate immediately
Pre-Migration: Audit Your Current Installation
Before switching interfaces, document your current Kanboard deployment to identify any edge cases.
Check your database engine. Kanboard SQLite installations require migrating to PostgreSQL or MySQL first—FrankBoard does not support SQLite for production use due to concurrency limitations. The SQLite-to-PostgreSQL migration is a standard Kanboard operation documented in their official wiki and should be completed before FrankBoard deployment.
Inventory active plugins. Note which Kanboard plugins your team depends upon. FrankBoard implements core Kanboard functionality natively; common plugin features like Gantt charts, calendar views, and analytics are built into the standard interface. Specialized plugins without FrankBoard equivalents may require workflow adjustment.
Verify backup integrity. Confirm your automated backups capture both the database dump and the data/ directory containing file uploads. Test a restore procedure on a separate system before proceeding.
The Migration Procedure
Step 1: Container Preparation
FrankBoard distributes as a Docker image with the same environment variable conventions as Kanboard. Your existing docker-compose.yml requires minimal modification.
Replace the Kanboard image reference with FrankBoard, keeping your database connection string identical. The container expects DATABASE_URL in standard format:
DATABASE_URL=postgres://user:password@db:5432/kanboard
Volume mounts for file attachments should point to the same host directory your Kanboard container currently uses. FrankBoard recognizes the files/ subdirectory structure without reorganization.
Step 2: Database Connection Verification
Start FrankBoard with your existing database in read-only mode initially by setting MAINTENANCE_MODE=true in environment variables. This allows the application to boot, verify schema compatibility, and report any unrecognized tables or version mismatches without writing changes.
Review container logs for schema validation messages. FrankBoard performs automatic column presence checks against expected Kanboard schema versions 1.2.35 and newer. Warnings about unrecognized tables indicate plugin data that will be preserved but inactive.
Step 3: Cutover Execution
Remove MAINTENANCE_MODE and restart the container. FrankBoard performs no destructive schema modifications on first boot. The application creates additional tables for its own feature extensions—user preferences for the new interface, notification settings, and cached view states—while leaving all original Kanboard tables unmodified.
Your first login uses existing credentials. The initial dashboard renders your projects with identical column configurations, swimlane structures, and task distributions. Task detail panels expose the same metadata: creation dates, assignees, due dates, priorities, tags, and comment histories.
Step 4: Validation Checklist
Verify these critical data points before declaring migration complete:
- Project count matches pre-migration
- Task counts per project align with Kanboard dashboard figures
- User role assignments preserved (admin, manager, user)
- File attachments open correctly from task cards
- Comment threads display chronologically with original authors and timestamps
- Activity stream shows historical events without gaps
What Changes in the Interface
The data remains constant; the interaction model evolves significantly.
Board navigation shifts from full-page reloads to dynamic column rendering with drag-and-drop task repositioning. Tasks moved between columns update via API calls without browser refresh, though the underlying column_id database update executes identically to Kanboard's server-side handler.
Filtering and search gain real-time response with indexed text search across titles, descriptions, and comments. The search syntax remains compatible: status:open assignee:me due:tomorrow functions as expected, now with autocomplete suggestions.
Mobile experience transforms from pinch-zooming a desktop layout to a native-responsive column stack with touch-optimized card handles and swipe gestures for common operations.
Keyboard shortcuts expand the existing set. All Kanboard shortcuts function; additional bindings for quick task creation, column collapse, and filter toggling layer on top without conflict.
Rollback Considerations
Because FrankBoard preserves the original database schema and creates only additive tables, reverting to Kanboard remains possible without data restoration from backup. Stop the FrankBoard container, restart your Kanboard container pointing at the same database, and the original interface resumes with all current data intact.
The additive tables FrankBoard creates—prefixed frankboard_—consume negligible storage and do not interfere with Kanboard operation. This two-way compatibility provides migration confidence for conservative teams.
Common Migration Concerns Addressed
Will custom fields transfer? Kanboard's custom fields plugin stores data in dedicated tables that FrankBoard preserves but does not display. Teams relying heavily on custom fields should evaluate whether simple task boards without custom fields align with their workflow, or maintain Kanboard for projects requiring that extension.
Does the API change? FrankBoard implements Kanboard's JSON-RPC API for backward compatibility with existing integrations, while adding a modern REST API with OpenAPI documentation. Webhook configurations and external tool connections function without modification.
What about performance? The React frontend reduces server round-trips through local state management and optimistic updates. Database query patterns remain similar to Kanboard's; no additional indexing is required for equivalent performance.
Key Takeaways
- FrankBoard reads Kanboard's native database schema directly—no export, import, or transformation process exists between the two systems
- Migration requires only repointing your Docker container to a FrankBoard image while preserving database connection and file volume mounts
- All core data structures—projects, tasks, users, columns, swimlanes, tags, comments, attachments—transfer without modification or loss
- The original Kanboard tables remain untouched; FrankBoard creates only additive tables, enabling clean rollback if needed
- SQLite installations must migrate to PostgreSQL or MySQL first, following standard Kanboard procedures
- Interface modernization occurs in the presentation layer while the proven backend task engine continues operating unchanged