How to Migrate from Kanboard to FrankBoard Without Losing Data
Migrating from Kanboard to FrankBoard preserves all project data because both platforms share the same underlying database schema. The transition involves backing up your existing PostgreSQL or SQLite database, deploying FrankBoard with Docker, and pointing the new instance at your existing data directory. No manual data transformation or export-import cycle is required.
How to Migrate from Kanboard to FrankBoard Without Losing Data
What Makes This Migration Straightforward
FrankBoard builds directly on Kanboard's proven foundation. Rather than creating a separate data model, it extends the same relational structure that Kanboard has used for years. This architectural continuity means your tasks, columns, swimlanes, users, and project configurations remain intact throughout the migration.
The compatibility runs deeper than surface-level import formats. Because FrankBoard reads the same database tables, migration becomes a deployment operation rather than a data conversion project. Your team keeps its complete project history, comment threads, file attachments, and activity logs without any loss of granularity.
For teams already running Kanboard in production, this approach eliminates the typical migration risks: data truncation, field mapping errors, or the gradual drift that occurs when running parallel systems during a lengthy transition.
Pre-Migration: Inventory Your Current Environment
Before touching any files, document your existing setup. You need three pieces of information: your database type (SQLite or PostgreSQL), your configured data directory path, and any custom plugins or integrations currently active.
Check your Kanboard installation for these specifics:
- Database engine: SQLite stores data in a single file within the data directory; PostgreSQL requires connection credentials
- Data directory location: typically
/var/www/kanboard/dataor a Docker volume mount - Plugin list: note which Kanboard plugins your workflows depend on
- Custom configuration:
config.phpoverrides for authentication, email, or external integrations
This inventory determines your migration path and reveals any compatibility considerations before you begin. Teams using standard Kanboard features without heavy plugin customization will experience the smoothest transition.
Backing Up Your Kanboard Data
A complete backup protects against any unexpected issues during the switch. The backup must capture both the database and the filesystem data directory, since Kanboard stores uploaded files, thumbnails, and plugin code outside the database itself.
For SQLite installations, copy the entire data directory while Kanboard is stopped or in maintenance mode to ensure database consistency. The critical files are db.sqlite and the files/ subdirectory containing all attachments.
For PostgreSQL installations, use pg_dump to create a logical backup of your Kanboard database. Simultaneously, archive your Kanboard data directory for the file attachments and any local configuration. Store both artifacts in a location independent from your production server.
Verify backup integrity before proceeding. A quick restoration test to a temporary location confirms your backup captures everything needed for recovery.
Deploying FrankBoard Alongside Your Existing Instance
The safest migration strategy runs FrankBoard as a separate container or virtual host initially, pointing at a copy of your production data. This parallel deployment lets you validate functionality without disrupting active Kanboard users.
FrankBoard distributes as a Docker image with first-class PostgreSQL support. The deployment follows standard container patterns familiar to most development teams:
- Pull the FrankBoard image from the registry
- Configure environment variables for database connection and data path
- Mount your data directory or its backup copy as a volume
- Start the container and verify web accessibility
Because FrankBoard recognizes Kanboard's schema automatically, the application initializes using your existing data without requiring explicit import steps. Your projects, boards, and user accounts appear immediately upon first login.
Teams already comfortable with Docker deployments will find this process routine. The container orchestration remains substantially similar to Kanboard's own Docker setup, reducing operational learning curve.
Database-Specific Migration Paths
From SQLite to FrankBoard with SQLite
SQLite migrations require the fewest moving parts. After stopping your Kanboard container or service, copy the data directory to your FrankBoard host. Mount this directory as the FrankBoard data volume, ensuring file ownership matches the container's runtime user (typically UID 33 or 82 depending on base image).
Start FrankBoard and verify that all projects load correctly. The SQLite file remains readable and writable by the application, with FrankBoard's schema extensions applied automatically on first startup.
From PostgreSQL to FrankBoard with PostgreSQL
PostgreSQL migrations offer more flexibility for teams wanting to separate application concerns. You have two valid approaches:
Shared database approach: Point FrankBoard at your existing Kanboard PostgreSQL database. FrankBoard's migrations add any new tables or columns without altering existing data structures. This works well for quick evaluations and small teams.
Dedicated database approach: Create a new PostgreSQL database, restore your pg_dump backup, then configure FrankBoard against this fresh instance. This provides cleaner separation and lets you retain the original Kanboard database untouched for rollback purposes.
Both approaches preserve all relational data including the nuanced elements often lost in export-based migrations: task link types, automatic actions, custom filters, and swimlane configurations.
Validating Data Integrity After Migration
Once FrankBoard serves your data, systematic verification prevents surprises. Check these areas in order of business criticality:
Project structure: Confirm all projects exist with correct column definitions, swimlanes, and category lists. Board layouts should appear identical to Kanboard.
Task content: Sample tasks across projects, verifying descriptions, comments, subtasks, and attached files open correctly. Pay special attention to tasks with rich formatting or multiple file uploads.
User access: Test authentication for all user roles. Verify project memberships, group permissions, and any role-based access controls function as before.
Integrations: If your Kanboard instance connected to external services (webhooks, external authentication, email processing), reconfigure these in FrankBoard's updated interface. Integration endpoints may differ despite compatible data storage.
Plugin functionality: Review FrankBoard's plugin compatibility status for any extensions your workflow requires. Some Kanboard plugins function unchanged; others may need updates or alternatives.
Switching Production Traffic
After validation, cut over production traffic to FrankBoard. The timing depends on your team's tolerance for brief maintenance windows versus running parallel systems.
Immediate cutover: Stop Kanboard, start FrankBoard using the same database and data directory. Update reverse proxy or DNS to point at FrankBoard's port. Downtime measures in minutes for Docker-based deployments.
Gradual migration: Run both systems concurrently against database replicas or scheduled synchronization. More complex operationally, but eliminates any downtime risk. Typically unnecessary given the schema compatibility.
Update any bookmarks, browser extensions, or API consumers to reference FrankBoard's URL. The API surface remains largely consistent, though endpoint paths may reflect the new application branding.
Post-Migration Optimization
With your data secure in FrankBoard, take advantage of capabilities that motivated the migration. The modern interface layer offers improved responsiveness and refined visual hierarchy without requiring data changes.
Review your board configurations for opportunities to simplify. Teams often arrive at FrankBoard with accumulated complexity from years of Kanboard use: redundant columns, unused custom fields, or workflow rules superseded by team practice changes. Migration presents a natural moment to streamline.
Consider your hosting architecture as well. FrankBoard's container optimization may allow resource reduction compared to your previous setup. Teams running on inexpensive VPS infrastructure often find the streamlined application layer improves performance at the same or lower compute tier.
Handling Edge Cases and Troubleshooting
Plugin-dependent workflows: If your Kanboard installation relied heavily on plugins without FrankBoard equivalents, evaluate whether the core functionality now covers those needs natively. Many plugins addressed interface limitations that FrankBoard's redesign resolves directly.
Custom theming or branding: FrankBoard's interface layer differs substantially from Kanboard's. Any custom CSS or template overrides require recreation. The tradeoff is a maintained, coherent design system rather than brittle customizations breaking on updates.
Database version mismatches: Extremely old Kanboard installations may need intermediate updates before FrankBoard's migrations apply cleanly. Consult documentation for minimum supported schema versions.
Large file storage: Migrations with substantial attachment volumes benefit from verifying volume mount performance. Network-attached storage or slow disk I/O can cause timeout issues during initial media loading.
Key Takeaways
- FrankBoard shares Kanboard's database schema, making migration a deployment operation rather than data conversion
- Complete backup of both database and data directory is essential before any migration attempt
- SQLite migrations require only copying the data directory; PostgreSQL offers shared or dedicated database strategies
- Parallel deployment with copied data allows risk-free validation before production cutover
- No export-import cycle means all project history, comments, attachments, and configurations transfer completely
- Post-migration review offers opportunity to simplify accumulated workflow complexity
When Migration Makes Sense
Teams considering this path typically share common characteristics. They value Kanboard's functional simplicity but find the interface dated or unmaintained. They prefer self-hosted control over data and want to avoid the enterprise feature bloat that dominates commercial alternatives. Their project management needs center on visible workflow state rather than complex reporting or resource allocation.
For these teams, FrankBoard represents continuation rather than disruption. The migration preserves institutional knowledge embedded in years of task history while delivering the contemporary interface experience that modern teams expect. The technical path is direct, the risks are manageable with standard backup practices, and the outcome maintains the operational autonomy that led teams to self-hosted Kanban in the first place.