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: Launch 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:

The upload zone is the centerpiece — drop your .zip (or .enc if encrypted) directly here:

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 Your New Cluster

The second step of the wizard lets you configure your new Skycloak cluster:

Cluster Configuration

1. Cluster Name: Enter a descriptive name for your new cluster
2. Cluster Size: Choose Small, Medium, or Large based on your workload
3. Deployment Location: Select your preferred region (US, EU, Canada, Asia Pacific)

Admin Credentials (Recommended)

Providing your Keycloak admin credentials enables full management mode, which allows Skycloak to manage your instance completely. Without credentials, the cluster runs in semi-management mode.

Custom Domain (Optional)

You can bring your existing auth.yourcompany.com-style domain in this step. Just enter it — Skycloak registers the hostname, issues SSL, and verifies the domain automatically after launch. There’s no “Verify” button; live status (Pending → Verifying → Live) shows on the progress screen.

Branding & Extensions (Optional)

You can also upload a custom theme (.zip) and Keycloak extensions (.jar files) during the migration — they’re staged and applied after the cluster is up. These previously had to be configured manually after migration; they’re now baked into the wizard.

Advanced Options

• Keycloak Features: Enable or disable specific Keycloak server features (configured on the Target cluster step).
• Legacy /auth Path: Enable if your applications use the pre-17.0 /auth URL path (configured on the Source database step).

Pre-flight Check

The final step shows everything the wizard verified — database dump, source version, cluster name, region, admin credentials, custom domain, theme package, extensions. Anything failing turns red with a hint on how to fix it. Tick I’m ready to migrate and hit Launch migration.

Step 4: Monitor Migration Progress

Once you start the migration, you’ll be redirected to the Migrations page where you can track progress in real-time.

Migration Stages

1. Database Upload (a few minutes, depending on file size and connection speed)

   • File transfer to secure storage
   • Integrity and checksum verification

2. Cluster Provisioning (5-10 minutes)

   • Infrastructure setup in your selected region
   • Network and database configuration

3. Database Restoration (5-30 minutes, depending on database size)

   • Database restore into the new cluster
   • Keycloak startup with migrated data

Estimated Total Time

Progress Indicators

• Progress Bar: Shows overall completion percentage.
• Phase List: Six runtime phases (Validating dump → Provisioning cluster → Restoring data → Applying theme → Loading extensions → Health checks). The active phase’s indicator pulses; finished phases turn green.
• Real-time Updates: Progress updates automatically via live streaming. Safe to leave the tab — the page stays on a confirmation screen when finished (no redirect), and the browser tab title flips to ✓ Migration complete while the tab is hidden so you can tell at a glance.
• Custom domain card (if you set one): the progress screen shows the CNAME you need to add and the live verification + SSL state (Preparing → Verifying → Live). No “Verify” button to click — Skycloak verifies automatically in the background.

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'
});

Post-Migration: Custom Domain Setup

After your migration completes, you can configure custom domains, themes, and extensions from the cluster settings:

Custom Domain

You can also bring your custom domain during the migration wizard (step 4) — that’s usually the smoothest path because Skycloak registers the hostname at launch so SSL is in place by the time you flip your DNS. There’s no “Verify” button to click anywhere; we verify the domain and issue SSL automatically in the background, and the progress screen shows live status (Pending → Verifying → Live). The 48-hour give-up applies — if the DNS record never lands we stop polling.

For domains added after the migration:

1. Navigate to your cluster’s Domain Settings page
2. Add your custom domain (e.g., auth.yourdomain.com)
3. Update your DNS with a CNAME record:

Type: CNAME
Name: auth.yourdomain.com
Value: [provided by Skycloak]
TTL: 300

That’s it — no extra step. Status moves from pending to active on its own once DNS propagates; the Custom Domains page updates without you having to refresh or click anything.

Custom Themes

Upload your custom themes from the Branding page in your cluster settings.

Extensions

Install extensions from the Extensions page in your cluster settings.

SSL Certificate

Skycloak automatically provisions and manages SSL certificates for your custom domain.

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 15-45 minutes depending on:

• Database size (most significant factor)
• Network upload speed

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 downtime on your source Keycloak while the migration runs. Typical migration times:

• Small databases (< 1 GB): 10-15 minutes
• Medium databases (1-5 GB): 20-30 minutes
• Large databases (5-10 GB): 30-45 minutes

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