Installation

Accelerate Guru ships as a single binary. There is no JVM, no PHP runtime, no Node.js. The entire edge fits in approximately 18 MB and depends only on the kernel's TCP stack (plus OpenSSL for TLS). Pick your platform below.

#Server requirements & capacity planning

#Why the edge server can be small

Accelerate Guru is written in Rust with a fully asynchronous I/O model (based on Pingora, Cloudflare's open-source Rust proxy framework). Unlike PHP, which spawns a new process or thread per request, Rust uses a tiny state machine per connection — no stack allocation, no heap per request, no garbage collector. A single CPU core can drive tens of thousands of simultaneous connections.

On a warm cache, the work per request is:

1. Parse HTTP headers — ~1 µs
2. Look up the page in DragonflyDB — ~100–500 µs (network round-trip to loopback)
3. Send the cached bytes to the client — the bottleneck is the NIC, not the CPU

The result: the edge server's CPU barely moves under normal load. Most of its time is spent waiting on network I/O — and that is handled by the kernel, not by Accelerate Guru.

#Recommended configurations

#Solo setup (edge + Magento on the same server)

This is fine for small-to-medium stores (up to ~500K pages/day) and is the simplest deployment:

#Split setup (edge server separate from Magento — recommended for growth)

Run Accelerate Guru + DragonflyDB on a lightweight VPS and Magento on a dedicated server:

Visitors → [Edge VPS] ──(cache miss ~5%)──▶ [Magento Server]
              AG + Dragonfly                    PHP + MySQL
              2–4 vCPU / 8 GB                  8–16 vCPU / 32 GB+
              ~$20-40/month                     your existing server

This is the right architecture when:

• You want to scale Magento and the edge independently.
• You're adding Accelerate Guru to an existing Magento server that is already at capacity.
• You're deploying a global edge fleet with multiple regional nodes pointing at one central Magento.

The edge VPS handles virtually unlimited traffic. The Magento server only sees the cache misses — roughly 5–10% of real requests after warmup. A store receiving 1 million daily visitors may only generate 50,000–100,000 PHP requests per day at the Magento level. That changes what "powerful Magento server" you actually need.

#Minimum hardware requirements

#Concurrent connection capacity

Accelerate Guru can hold hundreds of thousands of simultaneous open connections on modest hardware:

To put that in perspective: a 2 vCPU / 4 GB VPS costing $20/month can serve 80,000 cached pages per second. A global flash sale generating 50 million page views in an hour is less than 14,000 requests per second — well within a single small server's capacity.

#Disk space planning for the image cache

AVIF-encoded images are stored on disk in image_cache_dir. The space needed depends on your catalogue size:

AVIF files are 60–90% smaller than the originals, so even large catalogues are manageable. Use a fast SSD — the image cache is read-heavy and latency-sensitive.

#Linux

Linux is the primary supported platform. All major distributions with a kernel ≥ 4.19 are supported. The binary requires glibc ≥ 2.17 (RHEL 7+, Ubuntu 16.04+, Debian 9+); a static musl build is also available for Alpine and minimal containers.

#Install with the one-line script (recommended)

curl -fsSL https://accelerate.guru/install | sudo sh
sudo systemctl enable --now accelerate-guru

The script automatically:

• Selects the correct binary (glibc vs musl, x86_64 vs aarch64)
• Detects AVX2 support on x86_64 CPUs and downloads the optimised build
• Verifies the SHA-256 checksum before installing
• Registers a systemd unit
• Seeds /etc/accelerate-guru/magento_ultra.ini with defaults

#Manual install

If you prefer to control the download:

# Choose the right variant for your system:
# accelerate-guru-linux-x86_64-glibc.tar.gz       (most servers)
# accelerate-guru-linux-x86_64-glibc-avx2.tar.gz  (Haswell 2013+ / AWS / GCP)
# accelerate-guru-linux-x86_64-musl.tar.gz         (Alpine / containers)
# accelerate-guru-linux-aarch64-glibc.tar.gz        (Graviton / Ampere)

VERSION=latest
curl -fsSL "https://accelerate.guru/dist/${VERSION}/accelerate-guru-linux-x86_64-glibc.tar.gz" \
  -o accelerate-guru.tar.gz
sha256sum -c <(curl -fsSL "https://accelerate.guru/dist/${VERSION}/accelerate-guru-linux-x86_64-glibc.tar.gz.sha256")
tar -xzf accelerate-guru.tar.gz
sudo install -m 0755 accelerate-guru /usr/local/bin/accelerate-guru
sudo accelerate-guru install

#Privileged port binding (without running as root)

The binary needs to bind ports 80 and 443. The installer sets the CAP_NET_BIND_SERVICE capability automatically on Linux:

sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/accelerate-guru

The systemd unit already includes AmbientCapabilities=CAP_NET_BIND_SERVICE, so if you used the installer, this is handled for you.

#File locations (Linux)

#Managing the service

sudo systemctl start   accelerate-guru    # start
sudo systemctl stop    accelerate-guru    # stop (graceful drain)
sudo systemctl restart accelerate-guru    # restart (rarely needed; config is hot-reloaded)
sudo systemctl status  accelerate-guru    # check status and last log lines
journalctl -u accelerate-guru -f          # follow live logs

#Uninstall (Linux)

sudo accelerate-guru uninstall    # removes systemd unit, stops service
sudo rm /usr/local/bin/accelerate-guru
sudo rm -rf /etc/accelerate-guru  # ← only if you want to remove config too

#macOS

macOS is supported for production and local development. Both Intel (x86_64) and Apple Silicon (M1/M2/M3, aarch64) are supported — Homebrew picks the correct binary automatically.

#Install with Homebrew (recommended)

brew tap accelerate-guru/tap
brew install accelerate-guru

#Start as a background service (launchd)

brew services start accelerate-guru

This registers a LaunchAgent that starts Accelerate Guru at login and restarts it automatically if it crashes.

Check status:

brew services info accelerate-guru

#File locations (macOS)

#Privileged ports on macOS

On macOS, ports below 1024 require root or a special entitlement. For local development, it is simpler to use non-privileged ports:

[server]
http_port  = 8080
https_port = 8443

If you need ports 80/443 in production, run the service as root via a launchd system daemon rather than a user agent. The accelerate-guru install --launchd command handles this.

#Manage the service manually

brew services stop  accelerate-guru
brew services start accelerate-guru
# Or directly:
accelerate-guru --from-dir /opt/homebrew/etc/accelerate-guru

#Uninstall (macOS)

brew services stop accelerate-guru
brew uninstall accelerate-guru
brew untap accelerate-guru/tap     # optional

#Docker / Container

A Docker image is useful for containerised environments, Kubernetes, and CI pipelines.

#Run with Docker

docker run -d \
  --name accelerate-guru \
  --network host \
  -v /etc/accelerate-guru:/etc/accelerate-guru:ro \
  -v /var/cache/accelerate-guru:/var/cache/accelerate-guru \
  ghcr.io/accelerate-guru/edge:latest

#Docker Compose

A ready-to-use docker-compose.yml is included in the install package:

version: "3.9"

services:
  accelerate-guru:
    image: ghcr.io/accelerate-guru/edge:latest
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./config:/etc/accelerate-guru:ro
      - ./cache:/var/cache/accelerate-guru
    environment:
      RUST_LOG: info

  dragonflydb:
    image: docker.dragonflydb.io/dragonflydb/dragonfly:latest
    network_mode: host
    restart: unless-stopped
    command: dragonfly --bind 127.0.0.1 --port 6379
    ulimits:
      memlock: -1

Start the stack:

docker compose up -d
docker compose logs -f accelerate-guru

#Environment variables in containers

All config keys can be overridden with environment variables. This is the recommended way to inject secrets:

docker run -e AG_LICENSE_KEY=live_xxx ... ghcr.io/accelerate-guru/edge:latest

Variable naming: uppercase section and key joined by _, prefixed with AG_. For example, [server] upstream_port = 8080 becomes AG_SERVER_UPSTREAM_PORT=8080.

#Warden.dev

For local Magento development with Warden, a ready-made configuration is available at accelerate-guru/warden-config.

Clone or download the repo, copy the .warden folder to your Magento project root, then start the environment:

warden env up -d

All settings are in .warden/config/magento_ultra.ini. Useful commands:

warden accelerate-guru restart   # apply config changes
warden accelerate-guru logs      # live log output
warden accelerate-guru status    # container health
warden accelerate-guru pull      # update image

The Accelerate Guru dashboard is available at https://yoursite.test/stats-ag.

#Kubernetes

For Kubernetes, deploy as a DaemonSet (one pod per node) or as a dedicated Deployment in front of your Magento pods. Use a ConfigMap for magento_ultra.ini and a Secret for the license key.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: accelerate-guru
spec:
  selector:
    matchLabels:
      app: accelerate-guru
  template:
    metadata:
      labels:
        app: accelerate-guru
    spec:
      hostNetwork: true   # access loopback services
      containers:
        - name: accelerate-guru
          image: ghcr.io/accelerate-guru/edge:latest
          env:
            - name: AG_LICENSE_KEY
              valueFrom:
                secretKeyRef:
                  name: accelerate-guru-secrets
                  key: license-key
          volumeMounts:
            - name: config
              mountPath: /etc/accelerate-guru
              readOnly: true
      volumes:
        - name: config
          configMap:
            name: accelerate-guru-config

#Adobe Commerce Cloud (managed environments)

Adobe Commerce Cloud is a managed, read-only environment — you cannot install arbitrary binaries on the server directly. The correct deployment approach is to run Accelerate Guru on a separate VPS that you control, then point it at the Adobe Cloud origin.

#Architecture

Visitor
   │
   ▼
Accelerate Guru VPS
(your server — same AWS/Azure region as Adobe Cloud)
   │  cache misses only
   ▼
Adobe Commerce Cloud origin
(your Magento, unchanged)

#Step-by-step

1. Provision a VPS in the same region as your Adobe Cloud environment. If Adobe Cloud runs on AWS eu-west-1, use an AWS EC2 in eu-west-1. The low inter-region latency means cache misses are fast (often < 5 ms additional overhead).

2. Install Accelerate Guru and DragonflyDB on the VPS using the standard Linux installer.

3. Configure the origin to point at your Adobe Cloud hostname. Adobe Cloud Pro environments expose a stable origin hostname (e.g. your-env-id.c123.magento.cloud):

[server]
upstream_addr = your-env-id.c123.magento.cloud
upstream_port = 443

[tls_ssl]
upstream_tls  = true    ; Adobe Cloud always uses HTTPS on its origin

4. Update your DNS to point your store domain at the Accelerate Guru VPS IP. Adobe Commerce Cloud is unchanged — it simply receives fewer requests because the edge caches 90–95% of them.

#Upgrading

#Linux / systemd

curl -fsSL https://accelerate.guru/install | sudo sh
# The installer replaces the binary and restarts the service gracefully.

Accelerate Guru drains in-flight requests before the old process exits — no requests are dropped during an upgrade.

#macOS / Homebrew

brew update && brew upgrade accelerate-guru
brew services restart accelerate-guru

#Docker

docker pull ghcr.io/accelerate-guru/edge:latest
docker compose pull accelerate-guru && docker compose up -d --no-deps accelerate-guru

#AVX2 and performance-optimised builds

On Linux x86_64 systems, two builds are available:

The install script detects AVX2 automatically via /proc/cpuinfo. All major cloud providers (AWS, GCP, Azure, DigitalOcean, Hetzner) use Haswell-or-newer CPUs in their VMs, so most server installs get the AVX2 build by default.

To manually check which build is running:

accelerate-guru --version
# → accelerate-guru 1.2.3
#   built with rustc 1.87