Configure Pointsman without guessing

Documentation / How-to / Configuration

A gateway's configuration covers several different jobs: connecting infrastructure, choosing models, granting access and controlling how requests behave. Putting all of those settings in one long list makes the product harder to learn. This guide starts with the change you want to make and shows where it belongs, when it takes effect and how to verify it.

Complete the quickstart first. The dashboard tour shows the corresponding screens.

Choose the right configuration surface#

The dashboard's effective-configuration surface reports selected operational settings. It is not a complete editor for every Spring property, secret or model record. The environment reference is generated from docker/.env.example; additional typed configuration is defined in the source and explained by the feature guides.

Understand the labels#

Restart required (boot) means the running process read the value at startup. Editing a file or exporting a draft does not alter that process.

Operator refresh (refreshable) means the setting supports a documented refresh path. It does not mean the UI changes the environment or invokes refresh for you. Use the feature's procedure; do not assume a generic refresh reloads everything.

Runtime value (live) means an appropriate management operation can update that value. Use its dedicated editor/API. Studio still only prepares a draft, even when the setting supports runtime changes.

Current value is what the connected gateway reports. Draft value is an unapplied proposal. Default is a fallback when you have not overridden the setting; it is not necessarily the current value. Read units alongside every number: an entry count, bytes, milliseconds and a monthly currency amount are different constraints.

Configure a local Compose installation#

The quickstart copies docker/.env.example to docker/.env. Edit your copy; keep the example as a documented template. Typical initial values are:

POINTSMAN_AUTH_PEPPER=<stable-random-secret-from-the-quickstart>
POINTSMAN_KEY_ENVIRONMENT=test
POINTSMAN_ADMIN_USERNAME=admin
POINTSMAN_ADMIN_PASSWORD=<your-admin-password>
OPENAI_API_KEY=<your-provider-api-key>

This is a fragment, not a complete .env. Keep the other required values from the quickstart, including the bootstrap provider-client requirements. An admin bootstrap password seeds an empty admin table; changing that environment variable is not a password-reset procedure for an existing account. Keep the key pepper stable and back it up with your deployment secrets.

There are two layers to understand:

1. Compose constructs the container environment. The repository uses both env_file and explicit environment entries. Explicit entries win over env_file; interpolation uses the shell environment ahead of values in --env-file.
2. Spring resolves gateway settings inside the container. Packaged YAML supplies settings, and external property sources can override them. An environment variable only helps if it is passed into the container and maps to the intended property. Avoid defining the same setting in several places.

Use the same Compose files and --env-file arguments every time. A shell export can make your new .env value appear ineffective; inspect your shell's overrides when that happens. Do not paste a rendered configuration containing secrets into an issue.

# Validate Compose syntax/interpolation without printing resolved secrets.
docker compose --env-file docker/.env -f docker/docker-compose.yml config --quiet

For an approved change in your local evaluation stack, recreate the gateway so it receives the new environment. This command affects the running gateway; schedule production changes through your rollout procedure.

docker compose --env-file docker/.env -f docker/docker-compose.yml up -d gateway
curl --fail --show-error http://localhost:8080/actuator/health/readiness

docker compose restart restarts the existing container; it does not apply a changed container environment. If readiness fails, inspect startup logs and the named validation failure before sending traffic.

Example: create a two-model routing group#

Suppose your application requests support-chat. You want to distribute eligible requests between two models, while keeping the application's model name stable. Both models must already exist, be enabled and be accessible to the intended key.

The group's configuration looks like this:

pointsman:
  routing:
    groups:
      support-chat:
        strategy: weighted-random
        candidates:
          - provider: openai
            model: gpt-4o-mini
            weight: 9
          - provider: openai
            model: gpt-4o
            weight: 1

These are example registered model identifiers, not a promise of current provider availability. Replace them with your configured entries. Weights are relative selection weights, not a guarantee that every ten requests split nine to one.

Routing → Create group can prepare this kind of YAML. It is a fragment to merge into the configuration your deployment actually loads. The stock Compose setup does not automatically load an arbitrary YAML file just because you downloaded it.

For the stock local Compose setup, one way to supply nested configuration is an entry in docker/.env:

SPRING_APPLICATION_JSON='{"pointsman":{"routing":{"groups":{"support-chat":{"strategy":"weighted-random","candidates":[{"provider":"openai","model":"gpt-4o-mini","weight":9},{"provider":"openai","model":"gpt-4o","weight":1}]}}}}}'

If you already use SPRING_APPLICATION_JSON, merge into that JSON object rather than adding a second entry or discarding existing groups. Recreate the gateway, check readiness, then inspect Routing → Current settings. Call support-chat using the application API and inspect request evidence. A single successful answer does not statistically validate a weighting ratio.

Traffic-split guide · Routing strategies

Example: inspect and adjust a cache setting#

Open Configuration studio → Cache → Exact-cache capacity. Studio shows a friendly name, the current value, activation mode and technical key pointsman.cache.l1.max-size. Try a local draft, then review the before/after values. An exported fragment might look like:

pointsman:
  cache:
    l1:
      max-size: 12000

This is an illustrative value, not a sizing recommendation. L1 is also constrained by its configured weight budget. Read operational limits before increasing capacity. Merge the fragment with existing configuration, follow the restart requirement, then fetch current values again. Changing an entry cap alone does not prove a particular memory footprint or hit rate.

Use Configuration delivery to retain the reviewed baseline, proposed values and rollback values. Its verification reads current values and compares them with the package; it does not deploy the package or prove that a workload meets its targets.

Example: set an application's spending policy#

Use API keys or the relevant Budgets & limits scope. First inspect the key's owner and effective inherited limits. Then choose a cap/rule for that scope and save through the dedicated editor. Read back the effective limit and which ancestor binds it; the child's own value is not always the final constraint.

If you automate this through the admin API, check each endpoint's semantics. Many limits PUT operations replace the full set of fields: omitting a field can remove that cap. Do not assume a partial JSON object is a patch.

Gateway usage and cost can include estimates, especially for interrupted streams. Budget controls are not a provider-invoice hard cap. A fenced/unverifiable budget store needs its documented recovery procedure, not a larger cap or an automatic counter reset. Keys and budgets · Admin API · Operating notes.

Read back the effective settings#

In the dashboard, use Fetch current values and check that the fetch succeeded. An administrator can also inspect the same selected configuration surface with Basic authentication; curl prompts for the password:

curl --fail-with-body --silent --show-error --user admin \
  http://localhost:8080/admin/control/effective | jq .

This endpoint reports the gateway instance that answered. With several instances, verify all intended replicas through your deployment tooling rather than assuming one load-balanced read proves fleet-wide activation. It does not replace the registry, effective-limit or guardrail-specific read APIs.

A repeatable change procedure#

1. State the intended behavior and affected scope. Save the existing configuration or current record and its relevant inherited settings.
2. Prepare a small change. Review types, units, supported bounds and activation mode.
3. Validate it in your normal development/staging workflow. Keep the complete configuration around partial exports and full-replacement API operations.
4. Apply it using the appropriate deployment or management operation.
5. Check readiness and read back the effective value or saved record.
6. Verify behavior with an authorized test request and inspect its evidence. For capacity, recovery or routing-quality changes, run the corresponding qualification.
7. If the result is wrong, apply the reviewed rollback through the same mechanism and verify again. Reverting configuration does not undo requests or charges.

Troubleshooting#

Reference material#

• Environment settings and defaults: generated catalogue.
• Resource limits and units.
• Admin API: authentication, request shapes and mutations.
• Deployment guide: networking, persistence and rollout requirements.
• Dashboard walkthrough: screens and task explanations.

See Dashboard configuration ownership for conditional registry edits, Jev partial deployment drafts, operational observations and intentional API/deployment-only scope.