YANPM/apps/agent/doc/usage.md

Usage and Examples

Running locally (development)

1. Build the agent (from repository root):

   cargo build -p agent
   

2. Run the agent with defaults (socket in current directory):

   ./target/debug/yanpm-agent
   

3. Run with explicit socket and nginx config directory:

   ./target/debug/yanpm-agent --sock /run/yanpm/yanpm-agent.sock --nginx-config-dir /etc/nginx/conf.d
   

HTTP over unix-socket examples (using socat / curl helper)

If you want to call the API from the shell, you can use socat to convert the unix socket to an HTTP stream, or use tools that support unix sockets directly (e.g. curl --unix-socket). Examples below use curl --unix-socket.

Validate a fragment by name and timestamp:

curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/validate \
  -H 'Content-Type: application/json' \
  -d '{"config_name":"example","timestamp":1234567890}'

Validate and reload (returns rc and ro):

curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/validate_and_reload \
  -H 'Content-Type: application/json' \
  -d '{"config_name":"example","timestamp":1234567890}'

Write a fragment (create or update):

curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/write_config \
  -H 'Content-Type: application/json' \
  -d '{"config_name":"example","timestamp":1234567890,"content":"server { listen 80; server_name example.local; }"}'

Status endpoint (health)

curl --unix-socket ./yanpm-agent.sock http://localhost/status

Notes

• Use the config_name and timestamp fields consistently: timestamp is typically a monotonic update ID from the caller ensuring unique file names.
• When running in containers, mount the host nginx config dir if you want the agent to write directly to host nginx configuration.
• The repository includes a runtime Docker image built by apps/agent/Dockerfile which bundles nginx and the yanpm-agent binary (via s6-overlay). Use that image when you want nginx and the agent colocated (the agent is intended as a runtime companion to apps/api).