Migrating Bitrix24 On-Premise from CentOS 7 to CentOS Stream 9: A Complete Guide

Why This Migration Is Urgent

CentOS 7 stopped receiving security updates in mid-2024, and Bitrix24 (Alaio) On-Premise (Alaio) now requires PHP 8.2 or higher - a version that CentOS 7's outdated package ecosystem cannot reliably supply, leaving your portal both insecure and unable to receive product updates.

Running a self-hosted Bitrix24 on an end-of-life operating system creates a compounding problem. First, no OS-level CVE patches means every unpatched vulnerability stays open indefinitely. Second, the Bitrix24 platform itself enforces a hard minimum of PHP 8.2 (as of early 2026); portals running older PHP versions lose the ability to install platform and marketplace updates. Third, the Bitrix Web Environment packages - Nginx, Apache, and associated PHP extensions - are tested and shipped against modern RHEL-family releases, not the frozen CentOS 7 userland.

Target OS options (as of 2026):

OS	Type	Notes
CentOS Stream 9	Official Bitrix recommendation	Ships with Bitrix Web Environment packages
AlmaLinux 9	RHEL 9 compatible	Community-supported, binary compatible
Rocky Linux 9	RHEL 9 compatible	Community-supported, binary compatible

All three are viable targets. CentOS Stream 9 is the option most explicitly covered by Bitrix's own tooling and is used in this guide.

For a broader look at why teams choose self-hosted over cloud, see Self-Hosted CRM: Why Choose Bitrix24 On-Premise for Data Sovereignty.

---

Why In-Place Upgrades Are Risky - and What to Do Instead

A direct in-place major-version OS upgrade (CentOS 7 → Stream 9) is not recommended for Bitrix24 servers because the jump spans two full RHEL generations, and the Bitrix Web Environment layers - custom Nginx builds, PHP ZTS packages, and Apache modules - are tightly coupled to the OS version they were installed on.

In-place upgrade tools exist, but they were not designed for the Bitrix Web Environment stack and frequently leave behind incompatible package combinations that are very difficult to untangle. The failure modes (broken PHP extensions, corrupt MySQL socket paths, SELinux denials on rewritten config paths) can take longer to fix than a clean migration.

The recommended approach:

1. Provision a new CentOS Stream 9 server.
2. Install the Bitrix Web Environment on the fresh OS.
3. Take a full backup on the old CentOS 7 host (files + database).
4. Restore onto the new server.
5. Upgrade PHP to 8.2 or higher as part of the restoration process.
6. Reconfigure all peripheral services (domain/DNS, SSL, cron, Push & Pull, integrations).
7. Run both servers in parallel, verify, then cut over DNS.
8. Decommission the old box only after a stable parallel-run period.

This approach also gives you an automatic rollback option: the old server stays up until you are satisfied.

See also: How to Move Self-Hosted Bitrix24 to a New Server: A Complete Migration Guide

---

Pre-Migration Checklist

Before touching either server, complete every item on this checklist - skipping any one of them is the most common cause of migration-day surprises.

Use this as a literal sign-off list with your team:

• Inventory the old server - OS version, kernel, PHP version, MySQL/Percona version, installed PHP extensions, Nginx/Apache version.
• Check Bitrix24 license status - confirm the license is active; note that moving to a new server requires license reactivation.
• Audit all integrations and webhooks - list every external service (telephony, ERP/accounting, e-signature, payment gateways) that calls your portal's domain or IP.
• Note custom cron jobs - export crontab -l for the bitrix and root users.
• Confirm backup storage is external - the backup archive must reside outside the application servers (NAS, object storage, or a separate backup server).
• Measure disk usage - du -sh /home/bitrix/www and database size; provision the new server with at least 20-30% headroom.
• Record SSL certificate details - whether Let's Encrypt (auto-renewable) or a purchased cert.
• Check Push & Pull server mode - cloud-hosted Bitrix push service or a local Bitrix Push Server 2.0 instance.
• Freeze changes - communicate a change freeze to all developers during the migration window.
• Schedule a maintenance window - plan the cut-over for a low-traffic period.

---

Step-by-Step Migration Table

The migration follows twelve sequential phases; completing them in order prevents the most common failure points, especially around PHP compatibility and license reactivation.

The old CentOS 7 host, the backup layer, and the new CentOS Stream 9 host interact during migration.

The flow starts on the old server: a full backup (files and database) is created and pushed to external storage. The new server pulls that backup, restores it into a freshly configured Bitrix Web Environment, and then peripheral services (DNS, SSL, Push & Pull, cron, integrations) are reconnected before the final DNS cut-over removes traffic from the old host.

flowchart LR
    OLD["Old Server\nCentOS 7 + PHP 7.x"]
    BACKUP["External Backup\nfiles + DB dump"]
    NEW["New Server\nCentOS Stream 9"]
    BWE["Bitrix Web Environment\nPHP 8.2+ / MySQL 8.x"]
    SERVICES["Peripheral Services\nSSL · DNS · Push & Pull\nCron · Webhooks"]
    TRAFFIC["User Traffic\n(DNS cut-over)"]

    OLD -->|"1. Full backup"| BACKUP
    BACKUP -->|"2. Restore"| NEW
    NEW --> BWE
    BWE --> SERVICES
    SERVICES -->|"3. Parallel run & verify"| TRAFFIC
    TRAFFIC -.->|"Decommission after stable period"| OLD

#	Phase	Action	Expected Result
1	Freeze & snapshot	Put portal in maintenance mode; take VM/disk snapshot on old server	Safe rollback point
2	Full backup - files	Archive /home/bitrix/www and custom config directories (/etc/nginx, /etc/httpd, /etc/php-zts.d, /etc/php.ini, /etc/my.cnf)	Compressed archive transferred to external storage
3	Full backup - database	Export all databases; verify dump integrity	Verified .sql.gz on external storage
4	Provision new server	Deploy CentOS Stream 9; open ports 80, 443, 22 on firewall	Clean OS accessible via SSH
5	Install Bitrix Web Environment	Run the official Bitrix environment installer; select PHP 8.2 or 8.3 and MySQL 8.x during setup	Bitrix Web Environment operational; menu.sh accessible
6	Restore files	Extract backup archive to /home/bitrix/www; verify ownership and permissions	Files in place; no permission errors
7	Restore database	Import dump into MySQL 8.x; check character set is UTF-8 and mbstring.func_overload=0 in php.ini	Portal database accessible; no encoding errors
8	Reconfigure PHP	Verify PHP ≥ 8.2 is active; set memory_limit = 256M, default_charset = UTF-8, mbstring.func_overload = 0; remove any xcache.cacher or legacy accelerator settings	PHP diagnostic in Bitrix admin shows green
9	Reconfigure services	Point domain to new server IP (internal hosts file first); install/renew SSL (Let's Encrypt); configure Push & Pull (cloud or local Bitrix Push Server 2.0); restore cron jobs; update webhooks and integration endpoints	All services respond on new host
10	Reactivate license	Log into Bitrix24 admin → license reactivation wizard	License active on new server
11	Update platform	Go to Marketplace → Platform Update → Install Recommended Updates; then update all Marketplace solutions	Portal on latest build; no update errors
12	Parallel run & cut-over	Run both servers simultaneously; test all critical workflows; when stable, update public DNS; decommission old server after a monitoring period	Migration complete; old server off

---

PHP Upgrade: What Changes and What to Watch

The jump from PHP 7.x (typical on CentOS 7) to PHP 8.2 or 8.3 is the most technically consequential part of this migration, and it must be treated as a compatibility event, not just a version bump.

Key points for the PHP upgrade during migration:

• Minimum version: PHP 8.2 is the hard minimum for Bitrix24 On-Premise as of early 2026. PHP 8.3 is recommended.
• Deprecated settings to remove: mbstring.func_overload must be set to 0 (or removed entirely) - any non-zero value blocks platform updates. mbstring.internal_encoding should be left empty; use default_charset = UTF-8 instead.
• Required extensions: GD, PHP XML, FreeType, Zlib compression, mbstring, POSIX and PCRE regex support, OPcache. Verify each is present after the environment install.
• OPcache: Use OPcache as the PHP accelerator; older accelerators (eAccelerator, XCache with caching enabled) are incompatible with PHP 8.x.
• memory_limit: Set to at least 256M in php.ini.
• Third-party Marketplace solutions: Any custom or third-party modules may need updates to be PHP 8.x compatible - audit these before the migration window and contact vendors if needed.

On BitrixVM-based setups, PHP can be upgraded through the menu.sh interface: 1. Manage servers in the pool → 8. Update PHP and MySQL. On a fresh CentOS Stream 9 server, this is handled at install time by selecting the appropriate PHP version in the Bitrix environment setup.

For hardware sizing on the new server, refer to Self-Hosted Bitrix24: Hardware Sizing Guide for 50 to 1,000 Users.

---

Key Gotchas and How to Avoid Them

The four migration failure modes we see most often are SELinux policy denials, license reactivation being forgotten until after DNS cut-over, Push & Pull misconfiguration causing chat outages, and file-attachment integrity issues after a flawed restore.

Work through each before the maintenance window:

SELinux and firewalld differences CentOS Stream 9 ships with SELinux enforcing by default. If the Bitrix Web Environment installer does not configure SELinux contexts correctly (or your custom Nginx build adds non-standard socket paths), you may see silent HTTP 502 errors. Verify SELinux audit logs (/var/log/audit/audit.log) immediately after the restore and before parallel-run testing.

License reactivation The Bitrix24 on-premise license is tied to the server. Moving to a new machine requires reactivation through the admin panel. Plan for this explicitly - it is easy to overlook when focused on data migration, and an inactive license blocks access to updates.

Push & Pull server Real-time features (chats, tasks, telephony, calendars, mobile app) depend on Push & Pull. On the new server, either re-point to the Bitrix cloud queue service or reinstall Bitrix Push Server 2.0. The deprecated Nginx-PushStreamModule (0.3.4/0.4.0) and Bitrix Push Server 1.0 are no longer supported. Verify the Push & Pull configuration under Settings → Module Settings → Push and Pull before declaring the migration complete.

File-attachment integrity After restoring the file archive, verify a sample of uploaded files (documents, images, video) are accessible through the portal interface, not just present on disk. Permission mismatches (wrong owner/group on restored files) are a common source of broken attachments.

MySQL version jump Moving from MySQL 5.7 (common on CentOS 7 setups) to MySQL 8.x on the new server introduces stricter SQL mode defaults. Test with the restored database before cut-over; look for errors related to ONLY_FULL_GROUP_BY or reserved keyword changes.

For post-migration hardening, see Self-Hosted Bitrix24 Security Hardening: 25-Point Checklist.

---

After Cut-Over: Verification and Ongoing Maintenance

Do not decommission the old CentOS 7 server until the new installation has run in production for at least one full business cycle - typically five to seven working days - with all integrations, reports, and automations confirmed operational.

Post-migration verification checklist:

• Portal loads via HTTPS on the public domain; SSL certificate valid.
• All users can log in (including SSO/LDAP if configured - see Active Directory, LDAP and SSO Integration with Self-Hosted Bitrix24).
• Real-time features (chats, notifications, mobile app) working - confirms Push & Pull is live.
• Telephony and VoIP integrations active and logging calls.
• Cron jobs executing on schedule (check Settings → Performance → Agents and Cron).
• All webhooks and external integrations (ERP, accounting, e-signature, payment gateways) sending and receiving data correctly.
• Full backup from the new server completed and stored externally - see On-Premise Bitrix24: Backup & Disaster Recovery Strategy.
• Platform and Marketplace updates installed on the new server.
• Monitoring (uptime, disk, CPU, MySQL replication if applicable) configured for the new host.

Once the above items are confirmed, you can safely power down and archive the old CentOS 7 server. For ongoing maintenance practices, refer to Bitrix24 On-Premise Updates & Maintenance: Versions, Patches and Best Practices.

---

Working with ACP Group on OS Migrations

ACP Group is a Bitrix24 Gold partner with 1,300+ completed projects. For teams that prefer to hand off the technical complexity, ACP Group performs CentOS 7 → CentOS Stream 9 OS migrations with a structured process designed for minimal downtime: scoping the existing environment, executing the fresh-server migration, managing PHP upgrade compatibility, and verifying all integrations before and after cut-over. Exact timelines and costs depend on portal size, number of integrations, and region - contact ACP Group for a scoped estimate.

---

Working with a partner on self-hosting. Want the control of self-hosted Bitrix24 without running the server yourself? ACP Group can deploy and operate it for you - see managed self-hosted Bitrix24, support & maintenance plans, or request a turnkey deployment quote.