PM2 deployment

Use this guide when you want to run the Blurt MCP server as a long-lived Node.js process on a VPS or plain Linux host. PM2 manages the process lifecycle; the server still expects TLS, public rate limits, request body limits and host routing to live in a reverse proxy such as Caddy, nginx, a CDN or your hosting platform.

PM2 is a good choice when you want:

• a small Node.js process manager with restart and boot integration;
• simple log streaming with pm2 logs and pm2 monit;
• deployment from a normal source checkout.

Configuration model

The PM2 ecosystem file is intentionally not the runtime configuration source. It exposes only BLURT_ENV_FILE, and the server loads all application settings from that file.

Repository example:

ecosystem.config.cjs

Runtime configuration file used by the example:

/home/you/.config/blurt-mcp/secret.env

Create the directory and environment file on the host:

mkdir -p /home/you/.config/blurt-mcp
chmod 700 /home/you/.config/blurt-mcp
$EDITOR /home/you/.config/blurt-mcp/secret.env
chmod 600 /home/you/.config/blurt-mcp/secret.env

Minimal public HTTP configuration:

NODE_ENV=production
LOG_LEVEL=info
HOST=127.0.0.1
PORT=3000
BLURT_HTTP_JSON_BODY_LIMIT=256kb
BLURT_RPC_URLS=https://rpc.beblurt.com,https://rpc.blurt.world
BLURT_PRICE_URL=https://api.blurt.blog/price_info

Keep BLURT_POSTING_KEY out of public HTTP deployments. If you need signing, use local stdio or a private trusted deployment with explicit external controls.

Install and build

From the checkout:

npm ci
npm run build
npm install -g pm2

Review the BLURT_ENV_FILE path in ecosystem.config.cjs before starting the service.

First start

pm2 start ecosystem.config.cjs
pm2 status blurt-mcp-server

Then configure the reverse proxy to send /mcp, /healthz and /readyz to the local process, for example 127.0.0.1:3000 when using the environment file above.

Validate the process and endpoint:

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz
MCP_URL=https://mcp.example.org/mcp npm run smoke:http

Reload vs restart

Use reload for normal deployments after changing code or environment configuration:

git pull --ff-only
npm ci
npm run build
pm2 reload blurt-mcp-server --update-env
npm run smoke:http

Use restart when you explicitly want a full stop/start cycle or when troubleshooting a stuck process:

pm2 restart blurt-mcp-server --update-env

--update-env matters when BLURT_ENV_FILE itself changes in the PM2 process environment. Changes inside the referenced secret.env are picked up by the next process start because the server loads that file at startup.

Logs and monitoring

Stream logs:

pm2 logs blurt-mcp-server

Show recent lines only:

pm2 logs blurt-mcp-server --lines 100

Open PM2's terminal monitor:

pm2 monit

In production, the Blurt MCP logger writes JSON lines to stderr with its own timestamp. The PM2 example therefore does not add PM2 timestamp formatting or custom output files. Use OS log rotation or pm2-logrotate for long-lived hosts.

Save and startup

After the process list is correct:

pm2 save
pm2 startup

pm2 startup prints a platform-specific command. Run that command if you want PM2 to restore saved processes after a reboot.

Stop or remove

Stop without deleting the PM2 process definition:

pm2 stop blurt-mcp-server

Remove it from PM2 entirely:

pm2 delete blurt-mcp-server

If you delete the process and want the saved boot state to match, run:

pm2 save

Ecosystem options used

Option	Value	Why it is used
script	dist/server.js	Runs the compiled HTTP entrypoint. Build before starting PM2.
cwd	__dirname	Makes script and fallback .env resolution independent of the shell directory.
exec_mode / instances	fork / 1	Avoids premature local clustering; scale at the reverse proxy/platform after measuring real traffic.
autorestart	true	Makes the process manager restart the server after crashes.
watch	false	Keeps production deployments from restarting on generated file or log changes.
max_restarts / min_uptime	10 / 10s	Limits rapid crash loops caused by bad builds or invalid configuration.
kill_timeout	5000	Gives Node a short grace period during restarts.
env.BLURT_ENV_FILE	/home/you/.config/blurt-mcp/secret.env	Points the server at the single runtime configuration file.

Options intentionally omitted

Option	Why it is omitted
interpreter	PM2 already uses Node for .js scripts.
time / log_date_format	Production logs already contain JSON timestamps from the application logger.
out_file / error_file	Log paths and rotation are host policy; PM2 defaults plus log rotation are sufficient for the example.
merge_logs	Useful mainly with multiple instances or cluster mode; this example runs one process.
restart_delay	max_restarts and min_uptime already cover crash loops without adding another timing policy.
max_memory_restart	Memory limits are host- and traffic-specific. Add one after observing baseline memory usage.

For advanced PM2 behavior, see the PM2 documentation for ecosystem files, restart strategies and log management.