Upgrading a WildFly or JBoss EAP manually can be error-prone and time-consuming. Fortunately, the JBoss Server Migration Tool helps automate this process by transferring relevant configuration and deployments from one WildFly version to another.
Step 1: Download the Migration Tool
Start by downloading the JBoss Server Migration Tool from the official GitHub releases page or build it from source if needed.
Unzip the downloaded archive and move into its directory:
cd jboss-server-migration-x.y.z
Step 2: Prepare the Source and Target Servers
Ensure you have:
- The source server, i.e. the older WildFly version you’re migrating from.
- The target server, i.e. the newer WildFly version you’re migrating to.
Both servers should be fully extracted directories, and not currently running.
For example:
../wildfly-26.0.0.Final(source)../wildfly-36.0.0.Final(target)
Step 3: Run the Migration
To start the migration, use the script provided in the tool:
./jboss-server-migration.sh --source ../wildfly-26.0.0.Final --target ../wildfly-36.0.0.Final
On Windows, use the .bat version of the script.
The tool will detect the source and target versions and guide you through an interactive process, proposing migration steps for configurations, deployments, and other settings.
Step 4: Run in Non-Interactive Mode (Optional)
If you want to run the tool as part of a CI pipeline or just prefer full automation, you can add the --non-interactive flag:
./jboss-server-migration.sh --source ../wildfly-26.0.0.Final --target ../wildfly-36.0.0.Final --non-interactive
This mode applies default decisions without user prompts and is useful when running the same migration multiple times.
Step 5: Review the Migration Report
After the process completes, the tool generates several reports summarizing what was migrated, skipped, or failed. These include:
- Migrated configuration files (e.g.,
standalone.xml) - Subsystem changes
- Deployment status
- Any skipped or failed tasks, with reasons
These reports are essential if you want to review or audit the migration results.
Final Tips
- Always test the target server after migration to verify functionality.
- Keep backups of both source and target directories before starting.
- Some custom configurations or unsupported subsystems may require manual adjustment post-migration.
The JBoss Server Migration Tool significantly simplifies WildFly upgrades, helping teams keep up with the latest features and security improvements without the pain of manual reconfiguration.