APM Deployment Guide — Advanced Process Manager

Socket & runtime files

APM's CLI and daemon talk over a Unix domain socket in a root-owned directory. Only root and members of group apm can open it; the daemon reads the connecting process's uid from the socket and decides per command what that caller may do (see who may run what in the manual).

Item	Path	Notes
Control socket	`/run/apm/apm.sock`	Directory `0750 root:apm`, socket `0660 root:apm`, both set without following symlinks. A daemon started by a non-root user (development) uses `$XDG_RUNTIME_DIR/apm/apm.sock`. The pre-2.8 abstract name `@apm` is still answered for root only, so a 2.7 CLI can verify the daemon it just installed; it goes away in 3.0.
PID file	`/run/apm/apm.pid`	Beside the socket since 2.9 (was `/root/.apm/apm.pid`). A non-root daemon keeps `~/.apm/apm.pid`. Removed on clean exit.
Config (user)	`~/.apm/config.conf`	Loaded automatically on daemon start if it exists.
Config (system)	`/etc/apm/apm.conf`	Also loaded automatically. Created by the installer (`install.sh`). Drop worker configs into `/etc/apm/apm.conf.d/` — symlinks there are followed because root made them; a symlink the deploy user puts in its place is not.
Log (user)	`~/.apm/apm.log`	Written when APM is running as a regular user.
Log (service)	`/var/log/apm.log`	Written when running as the systemd service set up by the installer; `0664 root:apm`.
Runtime dir	`/run/apm/`	Created by the unit (`RuntimeDirectory=apm`) or by the daemon itself when started another way.

Socket access control

Membership of group apm is the whole gate. The installer creates the group and adds the user who ran it; add anyone else with usermod (a new login is needed for the group to take effect). Root may do everything. A group member gets the read-only commands, may apm run workers that run as themselves, and may manage workers whose user is themselves; everything that reads or writes files as the daemon or touches every worker at once needs sudo.

# Let alice use the CLI (read-only + her own workers):
$ sudo usermod -aG apm alice

# A worker's own processes reach the socket only if their user is in the group —
# and are then bound by the same rules.

Checking the socket

# The socket and its mode
$ ls -la /run/apm/

# Listening sockets (the legacy @apm name shows too, for root only)
$ ss -xl | grep apm

# Is the daemon alive, and which version
$ apm -v

Hardening the service (optional)

The installer's unit already sets what is safe for every app: RuntimeDirectory=apm, OOMScoreAdjust=-900, LimitNOFILE=65536, ProtectKernelTunables, ProtectKernelModules, ProtectKernelLogs, SystemCallArchitectures=native, RestartSec=2 and StartLimitIntervalSec=0 so a crash-looping daemon is never parked in failed. Everything a worker inherits that could change what an app can do is left out on purpose. If your apps allow it, add a drop-in and test on a staging box first:

# /etc/systemd/system/apm.service.d/hardening.conf
[Service]
# Workers get a private /tmp: breaks apps that share sockets or files there with nginx, PHP-FPM, cron.
PrivateTmp=yes
# Files the daemon and the workers create are group-readable only: breaks a web server reading uploads.
UMask=0027
# Capabilities the daemon keeps; a worker running as root loses the rest (raw sockets, mounts, ...).
CapabilityBoundingSet=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_KILL CAP_NET_BIND_SERVICE CAP_SYS_RESOURCE CAP_SETPCAP CAP_AUDIT_WRITE
# No raw or packet sockets anywhere in the tree.
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK

$ sudo systemctl daemon-reload && sudo systemctl restart apm

Nginx integration

APM runs its own proxy layer, so Nginx sits in front as an SSL terminator and vhost router, forwarding to APM's bound ports. Always set trust_proxy true in the worker config so APM's Vanguard firewall sees real client IPs.

Set trust_proxy. Without it, Vanguard rate-limits and bans Nginx's loopback address, not your actual visitors. Every worker behind Nginx should have trust_proxy true;.

HTTP reverse proxy

APM worker on port 3000, Nginx terminates SSL and forwards HTTP traffic.

nginx.conf

server {
    listen       443 ssl;
    server_name  myapp.example.com;

    ssl_certificate      /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/myapp.example.com/privkey.pem;

    location / {
        proxy_pass          http://127.0.0.1:3000;
        proxy_http_version  1.1;
        proxy_set_header    Host               $host;
        proxy_set_header    X-Real-IP          $remote_addr;
        proxy_set_header    X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto  $scheme;
    }
}

# apm.conf — worker side
worker {
    name         myapp;
    exec         node;
    params       server.js;
    server       http://127.0.0.1:3000;
    trust_proxy  true;
}

WebSocket proxy

WebSocket upgrades require the Upgrade and Connection headers to be forwarded, plus a long read timeout so idle connections aren't killed.

nginx.conf

server {
    listen       443 ssl;
    server_name  myapp.example.com;

    ssl_certificate      /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/myapp.example.com/privkey.pem;

    location /ws {
        proxy_pass          http://127.0.0.1:3001;
        proxy_http_version  1.1;
        proxy_set_header    Upgrade            $http_upgrade;
        proxy_set_header    Connection         "upgrade";
        proxy_set_header    Host               $host;
        proxy_set_header    X-Real-IP          $remote_addr;
        proxy_set_header    X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_read_timeout  3600s;     # keep idle WS connections alive
        proxy_send_timeout  3600s;
    }
}

# apm.conf — worker side
worker {
    name         myapp;
    exec         node;
    params       server.js;
    server       ws://127.0.0.1:3001;
    trust_proxy  true;
}

HTTP + WebSocket on one domain

Route by path prefix — REST API on /, WebSocket on /ws. APM listens on two separate ports; Nginx splits traffic.

nginx.conf

server {
    listen       443 ssl;
    server_name  myapp.example.com;

    ssl_certificate      /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/myapp.example.com/privkey.pem;

    # WebSocket endpoint — must come before location /
    location /ws {
        proxy_pass          http://127.0.0.1:3001;
        proxy_http_version  1.1;
        proxy_set_header    Upgrade            $http_upgrade;
        proxy_set_header    Connection         "upgrade";
        proxy_set_header    Host               $host;
        proxy_set_header    X-Real-IP          $remote_addr;
        proxy_set_header    X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;
    }

    # HTTP API / everything else
    location / {
        proxy_pass          http://127.0.0.1:3000;
        proxy_http_version  1.1;
        proxy_set_header    Host               $host;
        proxy_set_header    X-Real-IP          $remote_addr;
        proxy_set_header    X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto  $scheme;
    }
}

# apm.conf — worker side
worker {
    name         myapp;
    exec         node;
    params       server.js;
    server       http://127.0.0.1:3000, ws://127.0.0.1:3001;
    trust_proxy  true;
}

Unix socket upstream

Instead of a TCP loopback port you can have APM bind its HTTP server to a Unix domain socket file — no port needed, no TCP handshake, marginally lower latency on the same host. Nginx connects with proxy_pass http://unix:… and an upstream block.

Socket path. In the APM config you can use a relative path like ./myapp.sock — APM resolves it against the worker's path directory. For example, if path is /opt/myapp, the socket will be at /opt/myapp/myapp.sock. Use that absolute path in your Nginx config. If you prefer a dedicated directory (e.g. /run/apm/), create it first: sudo mkdir -p /run/apm.

nginx.conf

# Define the upstream once, reuse across location blocks
# Use the absolute path that matches the worker's path + socket filename
upstream apm_myapp {
    server    unix:/opt/myapp/myapp.sock;
    keepalive 32;
}

server {
    listen       443 ssl;
    server_name  myapp.example.com;

    ssl_certificate      /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/myapp.example.com/privkey.pem;

    location / {
        proxy_pass          http://apm_myapp;
        proxy_http_version  1.1;
        proxy_set_header    Connection         "";  # enable upstream keep-alive
        proxy_set_header    Host               $host;
        proxy_set_header    X-Real-IP          $remote_addr;
        proxy_set_header    X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto  $scheme;
    }
}

# apm.conf — relative path resolves to worker's path directory
worker {
    name         myapp;
    exec         node;
    params       server.js;
    path         /opt/myapp;
    server       http://unix:./myapp.sock;  # → /opt/myapp/myapp.sock
    trust_proxy  true;
}

Socket file permissions. APM creates the socket file owned by the worker's user. Nginx's worker process (often www-data) needs read+write access. Either run both under the same user or add Nginx's user to the APM worker's group.

HTTP redirect to HTTPS

nginx.conf

server {
    listen       80;
    server_name  myapp.example.com;
    return       301 https://$host$request_uri;
}

Apache integration

Apache uses mod_proxy, mod_proxy_http, and mod_proxy_wstunnel for reverse proxying. Enable them once, then use VirtualHost blocks per app.

enable modules

$ sudo a2enmod proxy proxy_http proxy_wstunnel rewrite headers ssl
$ sudo systemctl reload apache2

Set trust_proxy. Same rule as Nginx — every APM worker behind Apache needs trust_proxy true; so Vanguard sees real client IPs from X-Forwarded-For, not the loopback address.