Server Configuration

This page explains where testudo-server reads its runtime configuration, how Helm provides that file, what each field controls, and where the Swagger / OpenAPI switch belongs.

Configuration File Location

The current disaster-server runtime reads a fixed relative path:

configs/config.yaml

The code constant is:

configs.DefaultConfigPath = "configs/config.yaml"

The file is loaded and validated before the server starts. server.host, server.port, and server.namespace must be present.

warning

The current code path does not wire a command-line --config flag into configuration loading. When a setting does not take effect, first verify that configs/config.yaml exists under the process working directory instead of assuming an arbitrary config path was used.

Configuration Sources By Launch Mode

Scenario	Source	Notes
Local start from the source repository	disaster-server/configs/config.yaml	Starting from the repository root makes the relative path resolve to this file.
Server container image	/app/configs/config.yaml	The image WORKDIR is /app and includes a default config file.
Helm deployment	configs.configYaml in Helm values	The chart renders a ConfigMap and mounts it to /app/configs/config.yaml.

With Helm, change the values entry:

configs:
  configYaml: |
    server:
      host: "0.0.0.0"
      port: 8080
      namespace: disaster-system

The chart renders that block as config.yaml and mounts it at:

/app/configs/config.yaml

After changing the ConfigMap or Helm values, make sure the server Pod is recreated so the runtime loads the new file.

Minimal Example

server:
  host: "0.0.0.0"
  port: 8080
  env: "prod"
  namespace: disaster-system

log:
  level: info

jwt:
  secret: "replace-with-a-long-random-secret"
  access_expire: 24h
  refresh_expire: 168h

swagger:
  enabled: false

license:
  enabled: true
  namespace: ""
  caPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt

Fields

server

Field	Critical	Description
server.host	Yes	Hertz listen address. Containers usually use 0.0.0.0.
server.port	Yes	Hertz listen port. The sample uses 8080; Service and container ports must match the deployment design.
server.env	Yes	Authentication boundary. In the current code, dev skips JWT middleware for /apis and protected /api route groups; non-dev values enable JWT middleware.
server.namespace	Yes	Namespace in the management cluster where server reads and writes Testudo resources. The default is disaster-system.

Do not set server.env=dev in production. That would bypass the business JWT middleware on API route groups that should be protected.

log

Field	Description
log.level	Supports debug, info, and error. Unknown values fall back to info.

The LogConfig struct still contains an output field, but the current startup path only reads log.level.

jwt

Field	Description
jwt.secret	JWT signing key. Replace the sample value outside local development and do not commit real secrets to public repositories.
jwt.access_expire	Access-token lifetime. The current code falls back to 24h when it is unset.
jwt.refresh_expire	Refresh-token lifetime. The current code falls back to 168h when it is unset.

Sample files may still show jwt.timeout, and the config struct still contains jwt.realm. The current authentication path uses access_expire, refresh_expire, and secret; do not use timeout as the access-token expiry override.

swagger

Field	Description
swagger.enabled	Registers Swagger / OpenAPI documentation routes when enabled. The code default is false.

When enabled, server exposes:

Path	Purpose
/swagger/	Swagger UI.
/openapi.yaml	OpenAPI YAML.
/openapi.json	OpenAPI JSON converted from YAML.

Example:

swagger:
  enabled: true

The contract source lives in the server repository:

openspec/specs/disaster-server-openapi.yaml

swagger.enabled only controls whether a running server registers the documentation routes. It does not change the contract file. Swagger routes are not mounted behind the business JWT middleware, so production exposure should be constrained by private networks, gateways, Ingress allowlists, or equivalent outer controls. See Swagger / OpenAPI Documentation for contract maintenance rules.

license

Field	Description
license.enabled	Enables server-side license logic. The current default is true.
license.namespace	Namespace for license-related resources. Empty means server.namespace.
license.caPath	CA file path used by the server for Kubernetes API access. Pods use the ServiceAccount CA path by default.

Kubernetes Connection Configuration Is Elsewhere

configs/config.yaml does not store the management-cluster kubeconfig and does not store business-cluster kubeconfigs.

• For the management cluster, server first uses in-cluster config when running in a Pod.
• For local runs outside a cluster, it falls back to the current user's $HOME/.kube/config.
• Source and target cluster credentials are stored through platform cluster configuration. Server builds remote clients from kubeconfig or token/endpoint data in Cluster resources.

If a business cluster is unreachable, first inspect the platform cluster credential, network path, and certificate details instead of changing the server YAML.

Common Changes

Disable Swagger In Production

swagger:
  enabled: false

Change Management Namespace

server:
  namespace: disaster-system

license:
  namespace: ""

An empty license.namespace follows server.namespace. Set it explicitly only when license resources must live elsewhere.

Change Token Expiry

jwt:
  secret: "replace-with-a-long-random-secret"
  access_expire: 12h
  refresh_expire: 168h

Troubleshooting Checklist

Symptom	Check First
Startup fails to read config	Whether configs/config.yaml exists under the process working directory.
Helm changes do not take effect	Whether values changed configs.configYaml, the ConfigMap updated, and the Pod was recreated.
Production APIs have no authentication	Whether server.env was accidentally set to dev.
/swagger/ returns 404	Whether swagger.enabled=true and the server restarted.
/openapi.yaml cannot find the spec	Whether the runtime image or working directory contains openspec/specs/disaster-server-openapi.yaml.
Remote business cluster connection fails	Platform cluster credentials, remote API endpoint, network, and certificates rather than the server YAML.