62 lines
2.1 KiB
Markdown
62 lines
2.1 KiB
Markdown
# Usage and Examples
|
|
|
|
Running locally (development)
|
|
|
|
1. Build the agent (from repository root):
|
|
|
|
```sh
|
|
cargo build -p agent
|
|
```
|
|
|
|
2. Run the agent with defaults (socket in current directory):
|
|
|
|
```sh
|
|
./target/debug/yanpm-agent
|
|
```
|
|
|
|
3. Run with explicit socket and nginx config directory:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
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`):
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
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)
|
|
|
|
```sh
|
|
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`).
|