Skip to content

Configuration ​

This page describes the intended configuration model for PiePLM. The project is in the design phase, so names and defaults may change before the first release. The principles, however, are stable: explicit settings, environment overrides and no secrets in the repository.

Precedence ​

Configuration is resolved in this order, highest priority first:

  1. environment variables
  2. a configuration file passed with --config
  3. built-in defaults

Environment variables use the PIEPLM_ prefix and uppercase snake case. For example, database.url becomes PIEPLM_DATABASE_URL.

Minimal configuration ​

A minimal deployment needs a database URL, a server secret and a public base URL:

yaml
server:
  host: 0.0.0.0
  port: 8080
  publicUrl: https://plm.example.com

database:
  url: postgres://pieplm:secret@localhost:5432/pieplm?sslmode=require
  maxOpenConnections: 20
  maxIdleConnections: 5

security:
  # Used to sign sessions and short-lived tokens.
  # Provide through PIEPLM_SECURITY_SECRET in production.
  secret: change-me
  sessionHours: 12

The secret must be generated with a cryptographically secure random source and stored in a secret manager or environment file outside version control. Rotating it invalidates existing sessions, which is the intended behaviour.

Settings by area ​

Server ​

KeyDefaultDescription
server.host127.0.0.1Interface to bind
server.port8080HTTP port
server.publicUrl—External URL used in links and callbacks
server.trustedProxiesemptyProxies allowed to set forwarded headers
server.maxBodyBytes52428800Upload limit per request

Bind to 127.0.0.1 when a reverse proxy terminates TLS. Bind to 0.0.0.0 only on a trusted network.

Database ​

KeyDefaultDescription
database.url—PostgreSQL connection string
database.maxOpenConnections20Connection pool ceiling
database.maxIdleConnections5Idle connections retained
database.migrationsautoauto, manual or off

In production, prefer manual migrations so that schema changes are reviewed and applied deliberately rather than at process start.

Authentication ​

KeyDefaultDescription
auth.modelocallocal or oidc
auth.sessionHours12Session lifetime
auth.apiKeyEnabledtrueAllow API keys for integrations
auth.oidc.issuer—OIDC issuer URL when enabled
auth.oidc.clientId—OIDC client identifier
auth.oidc.clientSecret—Provide through the environment

API keys should be scoped to a role and an organisation. A key issued to a reporting tool should not be able to approve changes.

Storage ​

KeyDefaultDescription
storage.driverlocallocal or s3
storage.local.path./data/filesAttachment directory
storage.s3.endpoint—S3-compatible endpoint
storage.s3.bucket—Bucket name
storage.s3.region—Region
storage.s3.accessKey—Prefer environment or instance role
storage.s3.secretKey—Prefer environment or instance role

Store large binaries outside the database. Back up the attachment volume and the database together so that metadata and files remain consistent.

KeyDefaultDescription
search.languagesimplePostgreSQL text search configuration
search.embeddings.enabledfalseEnable optional vector channel
search.embeddings.model—Embedding model identifier
search.hybrid.weightLexical0.7Lexical weight in fusion
search.hybrid.weightVector0.3Vector weight in fusion

PostgreSQL full-text search is the baseline. Vector search is an optional second channel and should be fused with lexical results rather than replacing them. See Search engine.

MCP ​

KeyDefaultDescription
mcp.enabledfalseEnable the MCP server
mcp.transportstdiostdio or http
mcp.readOnlytrueDisable write tools by default
mcp.authToken—Token for HTTP transport

Read-only access is the safe default for agents. Enabling write tools should require an explicit configuration change and a scoped token.

Workflow ​

KeyDefaultDescription
workflow.requireApprovalForChangestrueChanges need approval
workflow.requireApprovalForBomtrueBOM edits need approval
workflow.escalationHours72Reminder threshold

Approval requirements should not be configurable to the point of being disableable by the author of a change. Separate the permission to configure a workflow from the permission to approve within it.

Environment overrides ​

bash
export PIEPLM_DATABASE_URL='postgres://pieplm:secret@db.internal:5432/pieplm?sslmode=require'
export PIEPLM_SECURITY_SECRET="$(openssl rand -hex 32)"
export PIEPLM_SERVER_PUBLIC_URL='https://plm.example.com'

Never commit a real secret, even in an example file. Commit an .env.example with placeholder values and document each variable.

Validation and failure behaviour ​

Configuration is validated at startup. The process should fail fast, with a clear message, when:

  • the database URL is missing or unreachable
  • the security secret is missing or shorter than the required minimum
  • auth.mode=oidc but the issuer or client ID is absent
  • storage.driver=s3 but the bucket or credentials are missing
  • mcp.transport=http but no token is configured

A service that starts with invalid configuration is harder to diagnose than one that refuses to start.

Next steps ​

Released under the MIT License. Privacy Policy