Migrating from Self-Hosted Keycloak

This guide walks you through migrating from a self-hosted Keycloak installation to Skycloak, including your database, custom domains, themes, and extensions.

Why Migrate to Skycloak?

• Zero Maintenance: No more managing infrastructure, updates, or backups
• Automatic Scaling: Handle traffic spikes without manual intervention
• High Availability: Built-in redundancy and failover
• Expert Support: Direct access to Keycloak experts
• Cost Predictable: Fixed monthly pricing, no surprise infrastructure bills
• Security Updates: Automatic security patches and updates

Prerequisites

Before starting your migration, ensure you have:

1. Skycloak Account: Developer plan or higher (required for migration feature)
2. Database Access: Administrative access to your Keycloak PostgreSQL database
3. Database Tools: pg_dump installed on your database server
4. File Size: Database dump must be under 10GB when compressed
5. Supported Version: Keycloak version 20.x or higher

Migration Overview

The migration process consists of five main steps:

Step 1: Create Your Database Dump

For PostgreSQL Databases

Connect to your Keycloak database server and run the following commands:

# Create the database dump
pg_dump -h [hostname] -p [port] -U [username] -d [database_name] \
  --no-owner --no-acl --clean --if-exists \
  -f keycloak_backup_$(date +%Y%m%d_%H%M).sql

# Compress the dump (required for upload)
zip keycloak_backup.zip keycloak_backup_*.sql

# Verify the compressed size (must be under 10GB)
ls -lh keycloak_backup.zip

Replace the placeholders:

• [hostname]: Your database host (e.g., localhost, db.example.com)
• [port]: PostgreSQL port (default: 5432)
• [username]: Database username
• [database_name]: Your Keycloak database name (often keycloak)

Important Dump Options

The dump flags ensure compatibility:

• --no-owner: Removes ownership information
• --no-acl: Excludes access control lists
• --clean: Adds DROP statements for clean restoration
• --if-exists: Prevents errors if objects don’t exist

Step 2: Start the Migration Wizard

1. Log in to your Skycloak dashboard
2. Navigate to the Clusters page (shown at the top of this guide)
3. Click the “Migrate from Keycloak” button to start the migration wizard
4. The migration wizard will guide you through the process

Upload Your Database

The first step of the wizard provides a clean interface for uploading your database:

In this step:

1. Select Keycloak Version: Choose your current Keycloak version from the dropdown
2. Name Your Cluster: Enter a descriptive name for your new Skycloak cluster
3. Upload Database: Use the drag and drop area to upload your .zip file (supports .sql and .zip files up to 10GB)

Step 3: Configure Migration Options

Custom Domain Migration

If you have a custom domain (e.g., auth.yourdomain.com):

1. Check “Migrate my custom domain”
2. Enter your current domain name
3. After migration, you’ll need to update your DNS records

DNS Update Required: You’ll need to point your domain to Skycloak’s servers after migration.

Theme Migration

If you have custom login themes:

1. Check “Migrate custom themes”
2. Export your theme files from your current Keycloak:

   # From your Keycloak installation directory
   tar -czf themes.tar.gz themes/your-custom-theme/
3. Upload the theme archive in the wizard

Extension Migration

For custom Keycloak extensions:

1. Check “Migrate extensions”
2. Upload your extension JAR files
3. Extensions will be scanned for security before deployment

Step 4: Monitor Migration Progress

Once you start the migration, you’ll see real-time progress:

Migration Stages

1. Database Upload (5-30 minutes)

   • File transfer to secure storage
   • Integrity verification

2. Cluster Provisioning (5-10 minutes)

   • Infrastructure setup
   • Network configuration

3. Database Restoration (10-60 minutes)

   • Schema creation
   • Data import
   • Index rebuilding

4. Configuration (5-10 minutes)

   • Theme deployment
   • Domain setup
   • Extension installation

5. Final Verification (2-5 minutes)

   • Health checks
   • Service validation

Progress Indicators

• Progress Bar: Shows overall completion percentage
• Current Step: Displays what’s being processed
• Estimated Time: Updates based on your database size

Step 5: Post-Migration Verification

Access Your New Cluster

1. Once migration completes, click “Go to Cluster”
2. Note your new Keycloak admin console URL
3. Use your original admin credentials to log in

Verification Checklist

Verify the following have migrated correctly:

• Realms: All realms are present
• Users: User accounts and profiles
• Clients: Application configurations
• Identity Providers: Social login settings
• Groups & Roles: Permission structures
• Authentication Flows: Custom authentication
• Themes: Custom login pages (if migrated)

Update Your Applications

Update your applications to use the new Skycloak URLs:

// Old configuration
const keycloak = new Keycloak({
  url: 'https://auth.yourdomain.com/',
  realm: 'your-realm',
  clientId: 'your-app'
});

// New configuration
const keycloak = new Keycloak({
  url: 'https://your-cluster.skycloak.io/',  // Or your custom domain
  realm: 'your-realm',
  clientId: 'your-app'
});

Custom Domain Setup

If you migrated with a custom domain:

Update DNS Records

Add a CNAME record pointing to your Skycloak cluster:

Type: CNAME
Name: auth.yourdomain.com
Value: your-cluster.skycloak.io
TTL: 300

SSL Certificate

Skycloak automatically provisions and manages SSL certificates for your custom domain using Let’s Encrypt.

Migration Best Practices

Before Migration

1. Test in Staging: Run a test migration with a staging database first
2. Backup Everything: Keep your original database backup safe
3. Plan Maintenance Window: Schedule 2-4 hours for production migration
4. Notify Users: Inform users about the planned maintenance

During Migration

1. Stop Write Operations: Prevent database changes during migration
2. Monitor Progress: Stay on the migration status page
3. Keep Backup Ready: Have rollback plan if needed

After Migration

1. Test Thoroughly: Verify all authentication flows work
2. Monitor Performance: Check response times and user experience
3. Update Documentation: Document new URLs and configurations
4. Keep Old System: Keep old Keycloak running for 1-2 weeks as backup

Troubleshooting

Common Issues

Upload Fails

Problem: File upload stops or fails Solution:

• Check file size is under 10GB
• Ensure stable internet connection
• Try uploading during off-peak hours
• Contact support if issue persists

Migration Stuck

Problem: Progress stops or seems frozen Solution:

• Wait at least 10 minutes (large databases take time)
• Check the current step message for details
• Contact support with your migration ID

Users Can’t Login

Problem: Authentication fails after migration Solution:

• Verify realm settings match original
• Check client configurations
• Ensure redirect URIs are updated
• Review authentication flows

Version Compatibility

Frequently Asked Questions

How long does migration take?

Migration typically takes 1-3 hours depending on:

• Database size (most significant factor)
• Number of realms and users
• Network upload speed
• Optional components (themes, extensions)

Can I migrate during business hours?

We recommend migrating during low-traffic periods because:

• You need to stop writes to your database
• Users may experience brief interruptions
• You’ll need time for verification

What if my database is larger than 10GB?

For databases over 10GB:

1. Contact [email protected] for assisted migration
2. We can arrange direct database transfer
3. Alternative migration methods available

Can I keep my existing Keycloak version?

Yes! Skycloak supports multiple Keycloak versions. Your migrated cluster will run the same version as your source, and you can upgrade later if desired.

Is there downtime during migration?

Yes, you should plan for:

• Minimum: 1-2 hours for small databases
• Average: 2-4 hours for medium databases
• Large: 4-8 hours for complex migrations

Can I rollback if something goes wrong?

Yes, your original Keycloak remains untouched. You can:

1. Continue using your self-hosted instance
2. Retry the migration after addressing issues
3. Contact support for assistance

Getting Help

Support Channels

• Email: [email protected]
• Documentation: docs.skycloak.io
• Status Page: status.skycloak.io

When to Contact Support

Contact support for:

• Non-PostgreSQL database migration
• Databases over 10GB
• Custom migration requirements
• Migration errors or failures
• Performance concerns

Information to Provide

When contacting support, include:

• Migration ID (shown in wizard)
• Source Keycloak version
• Database size
• Error messages (if any)
• Time of migration attempt

Next Steps

After successful migration:

1. Review Analytics: Check the Insights dashboard for usage patterns
2. Enable Backups: Configure automated backups
3. Review Security: Check security settings and MFA
4. Optimize Performance: Review and optimize realm settings
5. Plan Upgrades: Consider upgrading Keycloak version