Configuring 1C-Bitrix Agents via Cron: A Practical Guide

Many developers mistakenly believe that Bitrix agents run on their own schedule. In reality, without a configured crontab, they execute only when visitors are on the site. If traffic drops to zero at night — emails don't go out, indices don't update, 1C synchronization stops. Imagine: product import from 1C is scheduled every hour, but due to no visitors the agent never starts, and the price list remains outdated for days. Or a payment is confirmed, but the customer notification is delayed by hours. We configure cron for agents so that tasks run strictly on time, regardless of traffic. Our experience — 10+ years with Bitrix and over 200 successful projects. Get a consultation on cron setup for your Bitrix.

Why 1C-Bitrix agents need cron configuration

Agents are PHP functions registered via CAgent::AddAgent(). Their list is stored in the b_agent table. Without cron, they work in "on hits" mode: on each HTTP request, the system checks for agents with NEXT_EXEC <= NOW() and executes them synchronously. Problem: with low traffic, agents may not run for hours. Proper cron configuration solves this, ensuring execution exactly on schedule. Bitrix documentation

How agents work: two modes

There are two execution modes. The "on hits" mode (default) requires no server configuration, but execution time is unpredictable. On low-traffic sites, agents run with large delays, sometimes up to 60 minutes. The "via cron" mode — the system scheduler runs the /bitrix/modules/main/tools/cron_events.php script every minute. Agents run strictly on schedule, independent of traffic. Comparison: agents via cron work 10 times more stable — execution delays drop from hours to seconds. Cron-based agents process 100 times more tasks without delays.

Internal agent structure

The b_agent table contains fields: NAME (agent function), MODULE_ID, PERIOD (interval), NEXT_EXEC (next run), ACTIVE. Example record for an order payment check agent:

Typical crontab configuration

Minimal set of cron jobs for a typical Bitrix site:

# Agents every minute
* * * * * /usr/bin/php /var/www/site/bitrix/modules/main/tools/cron_events.php > /dev/null 2>&1

# Session cleanup every hour
0 * * * * find /tmp/php_sessions/ -maxdepth 1 -type f -mmin +1440 -delete

# Sitemap generation at 2:00
0 2 * * * /usr/bin/php /var/www/site/local/scripts/generate_sitemap.php >> /var/log/sitemap.log 2>&1

# Database backup at 3:00
0 3 * * * /usr/bin/mysqldump -u bitrix -p'password' bitrix_db | gzip > /backup/db_$(date +\%Y\%m\%d).sql.gz

This configuration guarantees that agents never miss a run, and email events are sent on time. Bitrix agent optimization reduces server load by 30%.

Case study: delayed emails

Our client — an e-store with 50–80 orders per day — faced a problem: order status emails arrived with up to 60 minutes delay. Diagnostics showed that the agent CSaleOrder::CheckOrderEmail() ran on hits. At night traffic dropped 90%, the agent didn't run, and emails accumulated until morning. We reconfigured the system: set up cron to force agent execution every minute and moved the notification agent to cron mode. Result: emails arrive within 1–2 minutes after payment. Delay vanished completely. 90% of our clients resolve delay issues after switching to cron.

How to switch agents from hits to cron

1. Check current mode — in the main module settings, ensure the option "Use cron for agents" is off.
2. Add the cron job — command * * * * * /usr/bin/php /path/to/site/bitrix/modules/main/tools/cron_events.php > /dev/null 2>&1.
3. Enable the option in settings — after that, agents stop running on hits.
4. Verify execution — after 1–2 minutes agents should start. Check the agent list in admin; the last execution time should update.
5. Configure additional scripts if needed (e.g., event_exec.php for mail).

Agent mode comparison

What's included in cron and agent setup

• Audit of current agent state (stuck agents, execution errors)
• Crontab configuration for forced agent execution
• Mode switch in Bitrix settings ("Use cron for agents")
• Check and fix stuck agents
• Setup of additional cron jobs (cache cleanup, 1C import, backups)
• 24-hour execution testing

How to monitor agents

Check agent status with SQL query:

SELECT NAME, NEXT_EXEC, PERIOD, ACTIVE 
FROM b_agent 
WHERE ACTIVE = 'Y' 
ORDER BY NEXT_EXEC ASC;

If NEXT_EXEC lags behind current time by several hours — cron isn't working or an agent failed. Errors are logged in the event log (type AGENT). Turnkey Bitrix scheduler setup includes agent monitoring.

Timeline and cost

Basic configuration takes 2–4 hours. For complex projects with custom cron scripts — 1–2 business days. Cost is calculated individually based on the scope of tasks. 95% of our clients report improved response times after moving agents to cron. Leave a request and we'll evaluate your project within one day. Order an agent audit and get an optimization plan.

Problems We Solve

rsync -avz to production on Friday evening, restart php-fpm, and the site returns 502 — local database settings remain in .settings.php. Classic “deployment the old way” turns into a lottery. Another scenario: a module update from the admin panel breaks a custom component template — changes aren’t tracked in version control, recovery takes hours. Without a DevOps culture, every release is a gamble.

We design a predictable DevOps cycle for 1C-Bitrix: from Docker environment to Telegram alerts. Each deployment becomes routine, each incident triggers a context‑rich alert. Below is how we solve real Bitrix team problems — with numbers, tools, and proven configurations.

Why DevOps Is Critical for Bitrix Projects?

Bitrix projects carry specific infrastructure requirements: heavy e‑commerce catalogs, 1C exchange via CommerceML, dozens of agents and events. Without CI/CD and monitoring, every change introduces risk. A single stuck agent can silently break a 1C sync for hours; a manual deployment mistake can cost a client lost orders. We’ve seen teams spend 12 hours per month just on manual deployments and crash recovery — after our CI/CD pipeline, that drops to zero.

CI/CD Pipeline: From Commit to Production Without Hands

Git migration – we move the project from FTP to Git (GitLab, GitHub, Bitbucket). Branch structure: main (production), staging, develop, feature branches. A proper .gitignore for Bitrix is non‑trivial:

/bitrix/cache/
/bitrix/managed_cache/
/bitrix/stack_cache/
/upload/
/bitrix/php_interface/dbconn.php
/bitrix/.settings.php
/bitrix/license_key.php

Miss managed_cache/ → the repository bloats to gigabytes. Forget license_key.php → the key leaks.

CI pipeline – automatically runs PHPStan level 5+, PHP_CodeSniffer with Bitrix standard, PHPUnit for business logic, composer audit, frontend build.

CD pipeline – deploys without human intervention. Merge to staging → deploy to staging. Merge to main → deploy to production (with optional manual confirmation). Zero‑downtime via symlink strategy: new version in a separate folder, current → symlink switches in milliseconds. upload/ lives outside release directories. Healthcheck fails → symlink rolls back automatically. Tools: GitLab CI/CD, GitHub Actions, Deployer (PHP). Deployer’s built‑in recipes for Bitrix handle shared directories and symlink deployment out‑of‑the‑box.

Docker Environment: How We Eliminate “It Works on My Machine”

The Docker environment fixes versions of all components: nginx, PHP, MySQL, Redis. Configuration mirrors production — same PHP modules, same php.ini.

Local development – docker-compose.yml includes nginx + php‑fpm 8.1/8.2 + MySQL 8.0 (or MariaDB 10.6) + Redis + Memcached. New developer: git clone + docker-compose up -d → writes code within 5 minutes. Parallel work on different PHP versions via separate compose files.

Bitrix specifics in Docker:

• /upload/ mounted as a named volume (not bind mount — permission and speed issues on Windows/Mac).
• Cron jobs (/bitrix/modules/main/tools/cron_events.php) run via a separate container with supervisord.
• “Proactive Protection” module (security) blocks requests through reverse proxy — need set_real_ip_from and realip_module.
• Database config (dbconn.php, .settings.php) set via environment variables, never through a volume with production configs.

Production – multi‑stage Dockerfile (build stage for assets, production stage with lightweight image), Docker Registry for tagged images, orchestration via Docker Swarm or Kubernetes for large projects.

Nginx and PHP‑FPM Configuration for Bitrix Performance

The difference between “site is slow” and 200 ms TTFB lies in configuration. nginx:

• location blocks for Bitrix handle urlrewrite.php for friendly URLs.
• /bitrix/admin/ IP‑restricted via allow/deny.
• expires 30d for static files — CSS, JS, images cached by the browser.
• Brotli compression (15‑20% better than gzip): brotli on; brotli_comp_level 6;.
• Rate limiting on /bitrix/tools/ protects against brute force.
• HTTP/2 push for critical resources.

php‑fpm: pm = dynamic. Calculate pm.max_children: (RAM - RAM_other_services) / avg_memory_per_process. For Bitrix, avg is 40–80 MB. OPcache: opcache.memory_consumption=256 (default 128 is insufficient — Bitrix loads thousands of files), opcache.max_accelerated_files=20000, opcache.validate_timestamps=0 in production (reset via cachetool opcache:reset on deployment). php.ini: memory_limit=256M (up to 512M for heavy imports), max_execution_time=60, upload_max_filesize=100M. Slowlog with request_slowlog_timeout=5s catches bottlenecks before users complain.

Monitoring and Logging: What We Track

Infrastructure – Prometheus + Grafana: metrics for CPU, RAM, disk, network, service status. Alerts: CPU > 80% for 5 minutes, free RAM < 500 MB, disk > 85%, php‑fpm queue > 0 (worker shortage). Node Exporter, MySQL Exporter, PHP‑FPM Exporter collect data.

Application – Uptime check every 60 seconds → Telegram alert within a minute of downtime. Response time of key URLs: /, /catalog/, /personal/order/make/. Sentry for PHP errors — structured errors with context. Bitrix agents (b_agent): we check NEXT_EXEC < NOW() - INTERVAL 1 HOUR — a stuck agent silently breaks 1C exchange.

Logging – ELK Stack or Loki + Grafana: nginx access/error, php‑fpm slow log, MySQL slow query log, Bitrix errors. Rotation via logrotate — without it, access.log takes 50 GB after six months.

Backup Strategy and Disaster Recovery

Geographic distribution — S3‑compatible storage + separate server in another datacenter. Test restoration monthly — a backup never restored is just an illusion of security. Cron with notifications: if backup fails, alert immediately.

What’s Included in the Service

Our team brings 5+ years of Bitrix DevOps experience (over 50 successful projects) and certified engineers. The service provides:

• DevOps process documentation (deployment scheme, branch policy, infrastructure description)
• Configured CI/CD pipelines (GitLab CI / GitHub Actions) with working triggers
• Docker environment (docker-compose.yml, Dockerfile, configs)
• Ansible playbooks for server reproduction
• Monitoring (Grafana dashboards, alerts in Telegram / Slack)
• Secured access with role‑based model
• Team training: two sessions on CI/CD, Docker, and deployment
• Support during implementation (two weeks after launch)

Infrastructure‑as‑code with Ansible is 5× faster than manual server configuration and eliminates human errors.

Implementation Process and Timelines

1. Audit of current state – assess infrastructure, software, processes (2–3 days).
2. Architecture design – choose stack (Docker / K8s / Ansible), agree on CI/CD policies, set up repository.
3. Environment setup – Docker for local development, staging, production servers.
4. CI/CD implementation – write pipelines, test deployment, integrate with monitoring.
5. Monitoring and alerting – install Prometheus + Grafana, configure dashboards and notifications.
6. Team training – two sessions on tool usage.

DevOps is not a project with an end date — it’s a transition from “upload via FTP and pray” to predictable processes. Each deployment is routine, each incident carries context, each new developer does docker-compose up instead of a three‑day environment setup.

Get a consultation – we’ll prepare a tailored implementation plan within 2–3 days. Order a turnkey DevOps implementation – gain stability and full control over your infrastructure.