APISIX Reference Deployment

This deployment is the fastest path for teams who do not currently run APISIX and want to evaluate SafeLLM with a real gateway flow.

It is intentionally minimal:

APISIX as the ingress gateway.
SafeLLM sidecar as the prompt security decision engine.
Redis for cache.
httpbin as test upstream.

Reference deployment source:

safellm-oss/examples/apisix-reference/

What This Gives You

A working gateway + security-layer integration in minutes.
Concrete request flow: Client -> APISIX -> SafeLLM /auth -> Upstream.
A reproducible baseline for demos, presales, and architecture discussions.

Quick Start

git clone https://github.com/safellmio/safellm-apisix-gateway-sidecar.git
cd safellm-apisix-gateway-sidecar/safellm-oss/examples/apisix-reference
cp .env.example .env
docker compose up -d

Check services:

docker compose ps

Run smoke tests:

bash smoke-test.sh

Default endpoint:

http://127.0.0.1:19080

Routes

GET /health -> sidecar health through APISIX.
POST /v1/guard -> direct decision endpoint through APISIX.
POST /api/* -> protected upstream traffic (APISIX pre-check + proxy rewrite).
GET /direct/* -> bypass route for comparison.

Security Behavior

The reference stack supports both modes:

SHADOW_MODE=true (default): suspicious input is logged as would-block, request still passes.
SHADOW_MODE=false: suspicious input is blocked.

To enable block mode:

Edit .env:
Terminal window
```
SHADOW_MODE=false
```
Restart:
Terminal window
```
docker compose up -d --force-recreate
```

Request Filtering Path (APISIX Side)

/api/* route uses APISIX serverless-pre-function:

Read request body.
POST body to http://sidecar:8000/auth.
Interpret decision:
- 200: continue to upstream.
- 403: block.
- sidecar failure: controlled by SAFELLM_FAIL_OPEN.

This is the critical pattern for LLM security because the gateway needs body-level inspection, not only headers.

Configuration Knobs

APISIX_HTTP_PORT: host port for APISIX (19080 default in reference stack).
SAFELLM_TIMEOUT_MS: APISIX to sidecar timeout.
SAFELLM_MAX_BODY_SIZE: body limit in APISIX pre-check.
SAFELLM_FAIL_OPEN:
- false: safer default (fail-closed).
- true: higher availability, weaker security posture during sidecar outages.

Operations Checklist (Before Production)

Reference stack is for evaluation. For production, add:

TLS termination and cert automation.
APISIX admin plane hardening and auth.
Secret management (not plain env files).
Logs/metrics shipping to your observability backend.
Replica and failure-domain strategy for gateway, sidecar, and Redis.
Policy decisions on fail-open/fail-closed with incident runbooks.

Troubleshooting

Port already in use

Change .env:

APISIX_HTTP_PORT=29080

Sidecar cannot reach Redis

Validate container health:

docker compose ps
docker compose logs --tail=100 redis sidecar

Requests not blocked in malicious tests

Verify mode:

docker compose exec sidecar printenv SHADOW_MODE

If it is true, behavior is expected: log-only mode.

Cleanup

docker compose down -v