====== 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.

===== Routine checks =====

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

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

<code bash>
sudo /opt/bl-proxy/scripts/test-scoped-policy.sh
</code>

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.

===== Security checklist =====

  * 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.

===== Common failures =====

**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.

===== Updating the project =====

There is no automatic upgrade path. Review changes in the [[https://github.com/01ax/binarylane-scoped-api-proxy|source repository]], back up configuration, regenerate and validate the payload, then test updates away from production before rollout.