Operations, security, and troubleshooting

This gateway holds an account-wide BinaryLane API token. Treat the VPS as security-sensitive infrastructure: patch it, restrict access, review logs, back up configuration without secrets, and have a rotation plan.

sudo /opt/bl-proxy/scripts/status.sh
cd /opt/bl-proxy
sudo docker compose ps
sudo docker compose logs --tail=200 apisix caddy etcd

After changing users or roles, run the supplied policy test where suitable:

sudo /opt/bl-proxy/scripts/test-scoped-policy.sh

The project repository also contains a coverage checker. Its current bundled OpenAPI snapshot accounts for 116 operations: 115 explicitly mapped and one generic server-action request deliberately denied unless its body action type is recognised. That result can drift whenever the upstream API changes.

• Use HTTPS for internet-reachable deployments.
• Restrict SSH and public ingress to the smallest practical source range.
• Never expose APISIX ports 9080 or 9180, or etcd port 2379.
• Rotate the BinaryLane token and every user secret after suspected compromise.
• Review container versions, source changes, role mappings, and the upstream API regularly.
• Test permissions using non-production resources.
• Send JWTs only in the Authorization header.

Caddy cannot obtain a certificate

Check that the DNS A record resolves to the VPS, ports 80 and 443 are reachable, and no other process owns those ports.

The proxy returns 401

Generate a new JWT and confirm its sub claim matches the configured username. If the user's secret was rotated, old JWTs no longer work.

The proxy returns 403

The request is not allowed by the user's role, or the operation is unknown to the policy. Inspect the role manifest and APISIX logs; do not widen a role without understanding the operation.

The upstream returns 401

The master BinaryLane API token may be missing, expired, revoked, or malformed. Re-run activation or update the root-only .env file and redeploy. Avoid printing the token while diagnosing it.

Containers do not start

Run docker compose ps and inspect the relevant logs. Confirm the host has free disk and memory, and that the generated APISIX admin key replaced the bootstrap placeholder.

There is no automatic upgrade path. Review changes in the source repository, back up configuration, regenerate and validate the payload, then test updates away from production before rollout.