Tutorials
Migrating from Self-Hosted Keycloak

Migrating from Self-Hosted Keycloak

Migrate your existing Keycloak deployment to Skycloak. This guide walks you through migrating your database from self-hosted Keycloak to our fully managed platform.

Overview

Skycloak’s migration process helps you:

  • Transfer all user data including passwords (with encrypted export)
  • Preserve configurations for realms, clients, and roles
  • Choose your region — deploy to US, EU, Canada, or Asia Pacific
  • Monitor progress in real-time with live status updates

Why Migrate to Skycloak?

Eliminate Operational Overhead:

  • No more server management
  • Automatic updates and patches
  • Built-in backup and recovery
  • 24/7 monitoring and support

Reduce Costs:

  • No infrastructure expenses
  • Reduced DevOps requirements
  • Predictable monthly pricing
  • Included enterprise features

Improve Reliability:

  • 99.9% uptime SLA
  • Multi-region availability
  • Automatic scaling
  • DDoS protection included

Prerequisites

Before starting your migration:

Requirements Checklist

  • Skycloak account with Launch plan or higher
  • Admin access to your source Keycloak instance
  • PostgreSQL database export — pg_dump access to your Keycloak database
  • Keycloak version 20.0 or higher (older versions — contact [email protected])
  • Backup of your current Keycloak data
  • Maintenance window scheduled (typically 15-45 minutes)
ℹ️
Non-PostgreSQL Databases: If you’re using MySQL or MariaDB, contact [email protected] for assisted migration guidance.

Pre-Migration Assessment

Evaluate your current deployment:

  1. Check Keycloak version:

    ${KEYCLOAK_HOME}/bin/kc.sh version

  2. Assess database size:

    SELECT pg_database_size('keycloak') / 1024 / 1024 as size_mb;

  3. Count users and realms:

    SELECT COUNT(*) FROM user_entity;
SELECT COUNT(*) FROM realm;

  4. List custom providers:

    ls ${KEYCLOAK_HOME}/providers/

Step 1: Prepare Your Database Dump

Export from Source Keycloak

Connect to your Keycloak database server and create a PostgreSQL dump:

# 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

Optional: Encrypt Your Export

If your dump contains sensitive data you want to protect during transfer:

# Encrypt the zip file with AES-256
openssl enc -aes-256-cbc -salt -pbkdf2 \
  -in keycloak_backup.zip \
  -out keycloak_backup.zip.enc

You’ll provide the encryption password in the migration wizard. Encryption is required if you include user credentials in your export.

Step 2: Start the Migration Wizard

  1. Log in to your Skycloak dashboard
  2. Navigate to the Clusters page
  3. Click the “Migrate from Keycloak” button
  4. The migration wizard will guide you through three steps

Step 2a: Upload Your Database

  1. Select your Keycloak version from the dropdown
  2. Choose upload method: drag-and-drop your .zip file, or provide a public URL to your dump
  3. If encrypted: check the encryption box and provide your password

The wizard validates your file after upload (size, checksum, and encryption key if applicable).

Step 2b: Configure Your New Cluster

  1. Cluster Name: A descriptive name for your migrated instance
  2. Cluster Size: Small, Medium, or Large
  3. Deployment Region: Choose your preferred region (US, EU Central, Canada, Asia Pacific)
  4. Admin Credentials (recommended): Provide your Keycloak admin username and password to enable full management mode
  5. Advanced Options: Keycloak feature flags and legacy /auth path support

Step 2c: Review and Confirm

Review your migration configuration and confirm the checklist before starting:

Step 3: Monitor Migration Progress

After starting the migration, you’ll be redirected to the Migrations page with real-time progress tracking.

Migration Stages

  1. Database Upload — File transfer and integrity verification
  2. Cluster Provisioning — Infrastructure setup in your selected region
  3. Database Restoration — Database restore and Keycloak startup

Estimated Time

Database Size Estimated Time
< 1 GB 10-15 minutes
1-5 GB 20-30 minutes
5-10 GB 30-45 minutes

Step 4: Verify and Go Live

Access Your New Cluster

Once migration completes, click “Go to Cluster” to access your new Skycloak instance. Log in with your original admin credentials.

Manual Testing Checklist

Test critical functions:

  • Admin can log in to Keycloak console
  • Users can authenticate successfully
  • Password validation works
  • SSO flow functions correctly
  • API authentication works

Post-Migration Configuration

After verifying your migrated data, configure additional features from your cluster settings:

  • Custom domains — Domain Settings page
  • Custom themes — Branding page
  • Extensions — Extensions page
  • Realm mappings — Cluster settings

DNS Update (If Using Custom Domain)

If you previously used a custom domain, add it to your new cluster and update DNS:

Type: CNAME
Host: auth.yourcompany.com
Target: [provided by Skycloak for your region]
TTL: 300

Skycloak automatically provisions SSL certificates for custom domains.

Post-Migration Tasks

Immediate Actions

  1. Monitor closely for 24-48 hours
  2. Check performance metrics
  3. Review error logs
  4. Update your applications with the new Skycloak URLs
  5. Update documentation

Rollback Plan

If Issues Occur

Have a rollback strategy ready:

  1. Keep source Keycloak running (read-only mode)
  2. Document rollback DNS settings
  3. Test rollback procedure before migration
  4. Have support contact ready

Rollback Steps

If needed:

  1. Revert DNS to original server
  2. Restore source Keycloak to active
  3. Investigate issues with Skycloak support
  4. Plan remediation before retry

Troubleshooting

Common Migration Issues

Upload fails or times out:

  • Check file size is under 10GB
  • Ensure stable internet connection
  • Try the URL method as an alternative to direct upload

Migration stuck in processing:

  • Wait at least 10 minutes — large databases take time
  • Check the status badge for the current stage
  • Contact [email protected] with your migration ID

User authentication failures after migration:

  • Verify realm settings match your original configuration
  • Check client configurations and redirect URIs
  • Ensure you exported with credentials if you need password preservation

Migration Best Practices

  1. Stop writes to your source Keycloak before taking the database dump
  2. Take a fresh backup immediately before starting
  3. Export with credentials if you want users to keep their passwords
  4. Keep your source Keycloak running as a fallback for 1-2 weeks
  5. Test authentication flows thoroughly after migration
  6. Monitor for 48 hours after going live

Cost Considerations

Migration Costs

  • Migration feature: Included with Launch plan and above
  • Data transfer: No ingress charges
  • Same pricing: Pricing is the same regardless of which region you deploy to

Security During Migration

  • All transfers use TLS encryption
  • Uploaded files are encrypted at rest in S3
  • Optional AES-256 encryption for your database dump
  • Encryption keys are permanently deleted after migration completes
  • Uploaded database files are automatically cleaned up after migration

Getting Help

If you encounter issues during migration:

  • Email: [email protected]
  • Include: Migration ID, source Keycloak version, database size, and any error messages

Next Steps

After successful migration:

  1. Configure custom domains from your cluster’s Domain Settings
  2. Upload custom themes from the Branding page
  3. Install extensions from the Extensions page
  4. Review analytics in the Insights dashboard
  5. Update your applications to point to the new Skycloak URLs
Last updated on
Email Theme Customization GuideSetting Up Enhanced Branding