How to Migrate from Kanboard to FrankBoard
FrankBoard migration preserves all Kanboard data through a direct database transfer and file migration, requiring no manual CSV exports or task recreation. Existing users, projects, and attachments move intact because FrankBoard maintains schema compatibility with upstream Kanboard.
How to Migrate from Kanboard to FrankBoard
What Migration Actually Involves
Moving from Kanboard to FrankBoard is a self-hosted-to-self-hosted transfer, not a rebuild. Both applications share the same underlying database structure, which eliminates the data transformation headaches common in platform switches. Migration consists of three parallel workstreams: database export, file attachments, and environment configuration.
Pre-Migration Checklist
Complete these steps before touching production data.
- Verify your Kanboard version. FrankBoard supports migrations from Kanboard 1.2.14 and later. Earlier versions require an intermediate upgrade.
- Confirm database type. PostgreSQL and MySQL/MariaDB are both supported; SQLite migrations require an extra conversion step.
- Back up everything. Create a full database dump and tar archive of your
data/directory, including uploaded files and thumbnails. - Document your plugins. Audit active Kanboard plugins. FrankBoard ships with core equivalents for the most common ones, but third-party plugin data may need separate handling.
- Allocate maintenance window. Plan for 15–30 minutes of read-only time depending on dataset size.
Step-by-Step Migration Process
1. Export the Kanboard Database
For PostgreSQL:
pg_dump -h localhost -U kanboard_user kanboard_db > kanboard_backup.sql
For MySQL/MariaDB:
mysqldump -u kanboard_user -p kanboard_db > kanboard_backup.sql
For SQLite, copy the database file directly:
cp /var/www/kanboard/data/db.sqlite /backup/db.sqlite
2. Archive File Attachments
Kanboard stores uploads in its data/ directory. Preserve directory structure exactly:
tar czvf kanboard_files.tar.gz /var/www/kanboard/data/
This captures task attachments, avatars, and plugin-generated assets.
3. Deploy FrankBoard
Spin up FrankBoard using the official Docker Compose template with your preferred database. The project provides ready-to-use configurations for PostgreSQL and MySQL stacks.
# Minimal PostgreSQL example
services:
frankboard:
image: frankboard/frankboard:latest
environment:
- DATABASE_URL=postgres://fb_user:password@db:5432/frankboard
volumes:
- frankboard_data:/var/www/frankboard/data
db:
image: postgres:15
environment:
- POSTGRES_DB=frankboard
- POSTGRES_USER=fb_user
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
4. Import Database Into FrankBoard
With FrankBoard containers running but not yet accessed, import your dump:
PostgreSQL:
docker compose exec -T db psql -U fb_user frankboard < kanboard_backup.sql
MySQL:
docker compose exec -T db mysql -u fb_user -p frankboard < kanboard_backup.sql
SQLite: Replace the generated database file with your copied backup, then adjust permissions.
5. Migrate File Attachments
Extract your archive into FrankBoard's data volume:
docker compose run --rm frankboard tar xzvf /backup/kanboard_files.tar.gz -C /var/www/frankboard/
Verify ownership matches the container's web server user (typically www-data).
6. Run FrankBoard's Migration Helper
FrankBoard includes a built-in schema verification tool that flags any edge cases:
docker compose exec frankboard php cli migrate:verify
This checks for orphaned plugin tables, incompatible charset settings, or missing indexes. Address any reported issues before proceeding.
7. Update Reverse Proxy and DNS
Point your existing domain or internal hostname to the FrankBoard container. No client reconfiguration is needed if URLs remain identical. Users log in with existing credentials—FrankBoard inherits the password hashes directly.
Handling Plugin Data
FrankBoard replaces several common Kanboard plugins with native features: group management, calendar views, and Gantt charts are included without separate installation. Data from these plugins migrates automatically since FrankBoard recognizes their tables.
For plugins without FrankBoard equivalents, you have three options: - Export plugin data to JSON/CSV before migration and reference it externally. - Port the plugin yourself using FrankBoard's compatibility layer, which preserves the Kanboard plugin API. - Archive the data and run the plugin in parallel on a frozen Kanboard instance for historical lookup.
Post-Migration Verification
Validate these items before announcing completion: - All projects and boards render without 500 errors. - Swimlane configurations match pre-migration layout. - File attachments open correctly from task cards. - User permissions and group memberships persist. - API tokens function for any integrated tools.
Run a smoke test by creating a test task, moving it across columns, and attaching a file.
Rollback Procedure
If issues emerge, FrankBoard's containerized deployment makes rollback straightforward. Stop the FrankBoard stack, restore your original Kanboard from the pre-migration backups, and reactivate your previous reverse proxy target. Your downtime is bounded by how quickly you can restore database and files—typically under five minutes with practiced procedures.
Key Takeaways
- Database schema compatibility between Kanboard and FrankBoard enables direct dump-and-restore migration without data transformation.
- File attachments require explicit transfer of the
data/directory; they are not included in SQL dumps. - Existing user credentials, project structures, and task histories migrate completely—no user re-invitation or task recreation needed.
- Plugin data handling varies: native FrankBoard features absorb common plugin functions, while third-party plugins may need manual archival.
- Docker-based deployment simplifies both execution and rollback, with the entire process completable in under 30 minutes for typical small-team instances.