Migrate CentOS to AlmaLinux: A Step-by-Step Guide to Using the almalinux-deploy Script

Why Migrate to AlmaLinux Now

CentOS 7 reached end-of-life in June 2024, meaning no more security updates. If you're still running CentOS 7 or 8 on production systems, you need a migration path. AlmaLinux offers a seamless transition with binary-compatible replacement for RHEL-based systems.

Prerequisites for Migration

• Supported OS version: CentOS 7.9+ or 8.4+ (CentOS Stream is also supported with appropriate flags)
• Root access: You need sudo or root privileges to run the script
• Network connectivity: System must reach AlmaLinux mirrors (download mirrors, updates)
• Backup strategy: Create a snapshot or backup before proceeding - this is critical for production systems
• Third-party repo awareness: Disable or update EPEL, Docker, and custom repositories before migration

Download and Prepare the Migration Script

Run these commands as root or with sudo privileges. The script is hosted on AlmaLinux's official GitHub repository.

# Download the official deployment script
curl -O https://raw.githubusercontent.com/AlmaLinux/almalinux-deploy/master/almalinux-deploy.sh

# Make it executable
chmod +x almalinux-deploy.sh

Validate with Dry-Run Check

Before making changes, run the script in check mode to validate your system:

# Perform prerequisite validation
./almalinux-deploy.sh --check

Expected output: The script will report if your system meets all requirements. Look for messages like "All prerequisites are met" and "Ready to migrate".

Note: The --check flag only validates prerequisites - it does not guarantee successful migration.

Execute the Migration

When you're ready to proceed:

# Run the actual migration
./almalinux-deploy.sh

The script will:

1. Backup existing repository files to /etc/yum.repos.d/*.bak
2. Download and import AlmaLinux GPG keys
3. Replace CentOS repositories with AlmaLinux repositories
4. Run dnf distro-sync to update all packages
5. Update system identification files
6. Log all actions to /var/log/almalinux-deploy.log

Post-Migration Verification

After the script completes, reboot the system:

reboot

Then verify the migration was successful:

# Check OS identification
cat /etc/os-release

# Verify repositories
dnf repolist

# Confirm AlmaLinux packages
dnf list installed | grep alma

# Check kernel version
uname -r

Expected Verification Results

Check	Expected Result
/etc/os-release	ID="almalinux", VERSION_ID="8" or "9"
dnf repolist	All repos point to mirrors.almalinux.org
dnf list installed	Packages like alma-linux-release, alma-linux-core, etc.
uname -r	Kernel version ending in .el8_x.alma or .el9_x.alma

Rollback Options if Migration Fails

If the migration fails or causes issues, you have two recovery paths:

Option 1: Repository Restoration (Partial Rollback)

If packages were partially updated but the system is still bootable:

# Restore original CentOS repositories
mv /etc/yum.repos.d/*.bak /etc/yum.repos.d/

# Reinstall CentOS packages (requires network access to CentOS mirrors if still available)
dnf distro-sync --releasever=7  # or 8

Option 2: Snapshot/Backup Restoration (Full Rollback)

If you created a VM snapshot or system backup before migration:

1. Restore the system to pre-migration state from your backup
2. Revert to the snapshot if using virtualization

Special Considerations

CentOS 7 to AlmaLinux 8

The script handles the yum to dnf transition automatically. The bootloader (grub2) configuration is updated for the new kernel.

Secure Boot on UEFI Systems

If secure boot is enabled, verify the AlmaLinux shim is properly enrolled before migration. The new kernel may fail to boot if keys aren't trusted.

Third-Party Repository Conflicts

Disable non-AlmaLinux repositories before migration:

# Temporarily disable EPEL and other repos
dnf config-manager --set-enabled epel  # re-enable after migration if compatible

Check the Migration Log

If issues occur, examine the detailed log:

cat /var/log/almalinux-deploy.log

Look for errors like package conflicts, GPG key failures, or network timeouts.

Final Validation Checklist

• System boots successfully into AlmaLinux
• All critical services (sshd, network, applications) are running
• Repositories are correctly configured for AlmaLinux mirrors
• Package versions are from AlmaLinux (check with rpm -qi packagename)
• Applications function as expected

Limitations and Important Notes

• AlmaLinux 9 requires CentOS 8 Stream - use the --almalinux-9 flag for that specific migration
• Production systems need testing - validate the migration on a staging clone first
• Repository compatibility varies - some third-party packages may need reinstallation or updates
• Backup is essential - the script modifies system files and packages; recovery without backup is difficult