Skip to main content

Configuration

Use this section to turn a working Jiandu installation into a deliberate deployment. It explains how to choose a database and blob store, expose the service through HTTPS, and add sign-in methods. The complete configuration reference remains the place to look up every accepted field and bound.

Jiandu combines settings in this order, with later sources winning:

  1. built-in defaults;
  2. a versioned JSON configuration file;
  3. environment variables;
  4. command-line options.

Unknown JSON keys and unknown command-line options stop startup. This is intentional: a misspelled security or storage setting should not be silently ignored.

Choose one source for each boundary​

A higher-precedence source replaces a complete tagged boundary; it does not safely fill in half of one. For example, set server.ingress.mode, public_origin, and trusted_proxy_cidrs together in JSON or set all three JIANDU_INGRESS_* variables together. Jiandu rejects partial or ambiguous boundaries.

Use the JSON file for durable, reviewable structure. Use environment variables for deployment-owned paths and public, non-secret overrides. Jiandu deliberately accepts sensitive values such as a PostgreSQL URL, WebDAV password, or OIDC client secret only through protected file references.

Start from the smallest configuration

Omitted settings keep their documented defaults. Copy the minimal example for the backend you want, validate it, and add tuning only when measurements or a concrete policy call for it.

A safe editing loop​

  1. Copy the repository's example configuration for the same version as your Jiandu binary.
  2. Change one concern at a time.
  3. Keep secrets out of JSON; use the documented file references or your deployment's secret mechanism.
  4. Validate before restarting.
  5. Restart and check both the health endpoint and a real browser workflow.

For a source checkout:

cp server/config/example.json server/jiandu.config.json
./scripts/run.sh -- --config jiandu.config.json --check-config
./scripts/run.sh -- --config jiandu.config.json

All current settings take effect after a restart. The validation command resolves the same precedence rules as startup without opening the service.

--check-config validates syntax, cross-field rules, state paths, and protected secret files. It is deliberately offline: it does not prove that a database, object store, identity provider, or proxy is reachable. After starting Jiandu, request /api/v1/health/ready through the real ingress path; that probe checks the selected database and performs a bounded write/read/delete check against blob storage.

Go deeper by concern​

A production change checklist​

For every configuration change:

  1. Save a verified recovery backup before changing a storage, database, or identity boundary.
  2. Keep the previous configuration and secret files recoverable.
  3. Run --check-config as the same operating-system user and with the same mounts as the service.
  4. Restart only one Jiandu process. PostgreSQL and remote blob storage do not make multiple application replicas supported.
  5. Check liveness and readiness through the public proxy, then exercise the affected workflow with non-sensitive sample data.
  6. Confirm that the backend port, database, storage endpoint, and identity assertion headers are not exposed more broadly than intended.
Last updated on