Skip to content

Override workflow and examples

Use override.conf to apply environment-specific values while keeping shipped defaults unchanged.

How to read this page:

  • Step: the action to perform in the override workflow
  • Files / commands: configuration files or bin/admin.sh commands involved
  • Why it matters: the operational reason behind the step
Step Files / commands Why it matters
1. Keep defaults unchanged db.conf, server-side monitor.conf / alpine.conf Preserves upgrade-safe, shipped defaults so patches do not collide with local edits.
2. Create or edit the override override.conf Holds your environment-specific values in one place under change control.
3. Scope the override override.conf Putting only environment-specific keys here keeps the diff small and reviewable.
4. Restart processes alpine-server, CLI processes {{ product_name }} reads configuration at startup, so changes apply only after restart.
5. Validate startup and health bin/admin.sh server info Confirms the server starts cleanly and is reachable before promoting changes.
  1. Keep default files (db.conf and server-side monitor.conf / alpine.conf) unchanged.
  2. Create or edit override.conf in your deployment config location (resources/, or external directory mounted to resources/ in containers).
  3. Put only environment-specific values in override.conf.
  4. Restart processes to apply changes.

  5. Validate startup and health checks. Start alpine-server, watch the logs for clean startup, then confirm reachability with a server info health check. Because the CLI is a remote gRPC client, create a host profile and log in first:

    # One-time, local-only setup (no server contact)
bin/admin.sh profile hosts create
bin/admin.sh profile authn login

# Health check against the running server
bin/admin.sh server info

    A successful server info response confirms the server build, the network path, the host profile, and the authenticated session are all working. See server info for output formats and details.

Example override.conf for production

# License data location
license.dataDir = "/var/lib/sae"

# Database overrides
db {
  dataSource.serverName = "postgres-prod.internal"
  dataSource.portNumber = 5432
  dataSource.databaseName = "pki"
  dataSource.user = "pki_app"
  dataSource.password = ${?ALPINE_DB_PASSWORD}
  dataSource.ssl = true
  dataSource.sslmode = "verify-full"
  dataSource.sslrootcert = "/etc/alpine-pki/certs/postgres-ca.pem"
  maximumPoolSize = 25
  minimumIdle = 10
}

# Monitoring and tracing overrides
monitor {
  enabled = true
  registries.prometheus.enabled = true
  registries.prometheus.http.host = "0.0.0.0"
  registries.prometheus.http.port = 8989
  tracing.enabled = true
  tracing.exporter = "otlp-grpc"
  tracing.endpoint = "http://otel-collector:4317"
}

Example server endpoint override

alpine {
  fail.on.missing.services = true
  endpoints = [
    {
      name = "public"
      bindHost = "0.0.0.0"
      port = 5051
      settings = "alpine"
      services = ["alpine-admin", "alpine-ca", "alpine-keyserver"]
    }
  ]
}

Operational best practices

  • Use environment variables for secrets (${?ALPINE_DB_PASSWORD}), not cleartext values in committed files.
  • Keep override.conf under change control per environment.
  • Restart and verify logs/health after each change before promoting to production.

FAQ

How do I validate an override change took effect? Restart `alpine-server`, confirm clean startup in the logs, then run `bin/admin.sh server info` against the running server. A successful response confirms the build, network path, host profile, and authenticated session.
Why does the health check need a host profile and login? The `alpine-admin-cli` is a remote gRPC client. Server-touching commands such as `server info` require a host profile created with `profile hosts create` and an authenticated session from `profile authn login`.
Where should I place override.conf? Put `override.conf` in your deployment config location under `resources/`. In containers, mount an external directory to `resources/` and place `override.conf` there so it persists across restarts.
How should I configure secrets in override.conf? Use environment substitutions such as `${?ALPINE_DB_PASSWORD}` instead of cleartext values in committed files, and keep `override.conf` under change control per environment.