APM Deployment Guide — Advanced Process Manager

Socket & runtime files

APM's CLI and daemon talk over an abstract Unix domain socket. Abstract sockets are kernel-managed: they exist only while the daemon is alive and leave no file on disk.

Item	Path / Name	Notes
CLI socket	`@apm`	Abstract socket (`\x00apm` internally). Visible with `ss -xl \| grep apm`. No file — kernel cleans it up on daemon exit.
PID file	`~/.apm/apm.pid`	Removed on clean exit. If the daemon crashes it stays behind; APM detects and replaces it on next start. When installed as a system service, `/root/.apm/apm.pid`.
Config (user)	`~/.apm/config.conf`	Loaded automatically on daemon start if it exists.
Config (system)	`/etc/apm/apm.conf`	Also loaded automatically. Created by `apm install`. Drop worker configs into `/etc/apm/apm.conf.d/`.
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 installed by `apm install`.
Runtime dir	`~/.apm/`	Created automatically on first run.

Socket access control

By default only the user that started the daemon (and root) can issue CLI commands. Add an OS group with allow_group in the daemon {} block to grant access to other users:

daemon {
    allow_group  apm-admin;  # members of this group may run apm CLI commands
}

# Add a user to the group:
$ sudo usermod -aG apm-admin alice

Checking the socket

# List abstract Unix sockets — look for @apm
$ ss -xl | grep apm

# Check if the daemon is alive
$ apm status

# PID of the running daemon
$ cat ~/.apm/apm.pid

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.