Managing Task Assignment in Agentic Workflows · FrankBoard

← Managing Task Assignment in Agentic Workflows · FrankBoard  ·  July 15, 2026

How to Migrate from Kanboard to FrankBoard Without Data Loss

FrankBoard maintains full database compatibility with Kanboard, which means migration requires only backing up your existing PostgreSQL or SQLite database, deploying FrankBoard with that same database connection, and letting the modern UI layer read your existing project data. No export-import dance, no task reconstruction, and no schema conversion is necessary because FrankBoard is built directly on Kanboard's data model.

How to Migrate from Kanboard to FrankBoard Without Data Loss

What Makes This Migration Different

Most project board migrations force teams through painful export-import cycles: CSV dumps that strip comments, XML transfers that lose attachments, or manual rebuilds that consume days. FrankBoard avoids this entirely because it shares Kanboard's underlying database schema. The migration is not a data transfer between incompatible systems—it is an upgrade to the presentation layer while your existing data remains exactly where it sits.

This architectural decision matters for small teams with limited migration windows. A developer deploying on a Friday evening can have the new interface running by Monday without asking colleagues to re-create their workflows.

Pre-Migration: Audit Your Current Kanboard Instance

Before touching any deployment scripts, verify what you actually have running. Log into your current Kanboard as an administrator and document:

Screenshot your active plugin list and save your config.php or environment variables. This inventory prevents surprises during cutover.

Check Your Kanboard Version

FrankBoard targets compatibility with recent Kanboard releases. If your instance has not been updated in years, consider upgrading Kanboard itself to a current stable version first. A stale database schema may require intermediate migration steps that FrankBoard does not handle automatically.

Step 1: Create a Complete Database Backup

This is the non-negotiable foundation. Your backup strategy depends on your database engine.

PostgreSQL Backups

For PostgreSQL, use pg_dump with custom format for maximum flexibility:

pg_dump -h your-db-host -U kanboard_user -F c -b -v -f "kanboard_backup_$(date +%Y%m%d).dump" kanboard_database

Store this dump file outside your server—S3-compatible object storage, another VPS, or encrypted local media. Test restoration to a temporary database before proceeding:

pg_restore --clean --if-exists -d test_restore kanboard_backup_YYYYMMDD.dump

Verify the test database contains expected project counts, task totals, and user records.

SQLite Backups

For SQLite, simply copy the database file while Kanboard is not writing to it. Stop your Kanboard container or process first to guarantee consistency:

cp /path/to/kanboard/db.sqlite /secure/backup/location/kanboard_backup_$(date +%Y%m%d).sqlite

Then verify file integrity:

sqlite3 /secure/backup/location/kanboard_backup_YYYYMMDD.sqlite "PRAGMA integrity_check;"

Step 2: Prepare Your FrankBoard Deployment Environment

FrankBoard distributes as a Docker image with explicit support for PostgreSQL. Your deployment options include a fresh VPS, the same server currently running Kanboard, or a container orchestration platform.

Minimal Docker Compose Configuration

Create a docker-compose.yml that connects FrankBoard to your existing database or a restored copy:

version: '3.8'
services:
  frankboard:
    image: frankboard/frankboard:latest
    environment:
      - DATABASE_URL=postgres://kanboard_user:your_password@db:5432/kanboard_database
      - DATABASE_DRIVER=postgres
    ports:
      - "8080:80"
    volumes:
      - frankboard_data:/var/www/html/data
      - frankboard_plugins:/var/www/html/plugins

  db:
    # Only needed if migrating database; omit if using external PostgreSQL
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=kanboard_user
      - POSTGRES_PASSWORD=your_password
      - POSTGRES_DB=kanboard_database
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./your_backup.dump:/docker-entrypoint-initdb.d/restore.dump

volumes:
  frankboard_data:
  frankboard_plugins:
  postgres_data:

Critical Environment Variables

FrankBoard recognizes Kanboard's configuration conventions. Map these explicitly:

Variable Purpose
DATABASE_URL Full connection string for PostgreSQL
DATABASE_DRIVER Must be postgres or sqlite
DATA_DIR Path to attachments and local files
PLUGIN_DIR Location for plugin storage

Step 3: Restore Database and Launch FrankBoard

For PostgreSQL migrations, initialize your database from the backup before first container start:

# Create empty database
createdb -h db-host -U postgres frankboard_target

# Restore from Kanboard backup
pg_restore -h db-host -U postgres -d frankboard_target kanboard_backup_YYYYMMDD.dump

Launch FrankBoard with the connection pointed at this restored database:

docker-compose up -d

Monitor logs for schema verification messages. FrankBoard performs automatic compatibility checks on startup and will halt with explicit errors if it detects unsupported schema versions.

Step 4: Verify Data Integrity

Do not announce the migration complete until you have spot-checked every data category. Log into FrankBoard with existing Kanboard credentials and confirm:

Automated Verification Query

For PostgreSQL-backed instances, run this diagnostic directly:

SELECT 
  (SELECT COUNT(*) FROM projects) as project_count,
  (SELECT COUNT(*) FROM tasks) as task_count,
  (SELECT COUNT(*) FROM comments) as comment_count,
  (SELECT COUNT(*) FROM users) as user_count,
  (SELECT COUNT(*) FROM task_has_files) as attachment_count;

Compare these totals against your running Kanboard instance before decommissioning.

Step 5: Handle Plugin and Integration Transitions

FrankBoard's modern UI layer does not guarantee compatibility with Kanboard's PHP plugin architecture. Evaluate each plugin from your inventory:

Plugins likely to work unchanged: Database-driven plugins that primarily store configuration and expose no custom UI elements. These often continue functioning because FrankBoard preserves the underlying tables.

Plugins requiring replacement: Interface-heavy plugins with custom CSS, JavaScript, or PHP templates. FrankBoard's React-based frontend cannot render these directly. Identify FrankBoard-native alternatives or accept temporary feature loss.

API-dependent integrations: Scripts using Kanboard's JSON-RPC API require endpoint updates. FrankBoard maintains API compatibility for core resources but may differ in authentication or response formatting. Test integrations in staging before production cutover.

Step 6: Cut Over Traffic and Decommission Kanboard

Once verification passes, redirect user traffic:

  1. Update reverse proxy: Point nginx, Traefik, or your load balancer from Kanboard to FrankBoard's port
  2. Update DNS: If running on new infrastructure, adjust A or CNAME records with appropriate TTL reduction beforehand
  3. Synchronize final changes: If Kanboard remained active during verification, repeat backup-restore for delta data or accept a brief maintenance window
  4. Stop Kanboard: docker-compose down or disable the legacy systemd service
  5. Retain backups: Keep your final Kanboard backup for 30 days minimum

Common Migration Pitfalls

Running both instances simultaneously on the same database: This causes locking conflicts and potential corruption. FrankBoard expects exclusive database access during its schema verification phase.

Forgetting attachment volume mounts: Tasks appear intact but file downloads fail because DATA_DIR points to an empty container filesystem. Always mount persistent storage for attachments.

Assuming plugin parity: Teams discover critical workflow dependencies on plugins only after cutover. The pre-migration inventory prevents this surprise.

Neglecting API consumers: Automated scripts fail silently when endpoints change. Audit your infrastructure for Kanboard API calls before migration.

Rollback Procedure

If critical issues emerge post-migration, reverting is straightforward because your original database remains unmodified if you followed the backup-restore pattern rather than in-place replacement:

  1. Stop FrankBoard containers
  2. Restart Kanboard with original database connection
  3. Update reverse proxy to original target
  4. Investigate FrankBoard issues in parallel without production pressure

For in-place deployments where FrankBoard modified the database, rely on your pre-migration dump for full restoration.

Key Takeaways

Original resource: Visit the source site
This page is part of a public answer resource for Managing Task Assignment in Agentic Workflows · FrankBoard.