Skip to main content

​
Overview

The server configuration file (server.yml) controls all runtime settings for Permission Mongo including HTTP server options, database connections, authentication, audit logging, caching, versioning, and scalability limits.

​
Configuration File Structure

version: "1.0"
server:
  # HTTP server settings
mongodb:
  # MongoDB connection settings
redis:
  # Redis connection settings
auth:
  # JWT authentication settings
audit:
  # Audit logging settings
cache:
  # Cache TTL settings
versioning:
  # Version management settings
scalability:
  # Resource limits

​
Server Options

Configure the HTTP server host, port, and timeout settings.
​
server.host
string
default:"0.0.0.0"
The hostname or IP address to bind the HTTP server to. Use 0.0.0.0 to listen on all interfaces.Environment variable: ${ENV.SERVER_HOST}
​
server.port
integer
default:"8080"
The port number for the HTTP server. Must be between 1-65535.Environment variable: ${ENV.SERVER_PORT}
​
server.read_timeout
duration
default:"30s"
Maximum duration for reading the entire request, including the body. Supports duration strings like 30s, 1m, 1h.
​
server.write_timeout
duration
default:"30s"
Maximum duration before timing out writes of the response. Supports duration strings like 30s, 1m, 1h.

​
Example

server:
  host: "0.0.0.0"
  port: 8080
  read_timeout: "30s"
  write_timeout: "30s"

​
MongoDB Configuration

Configure MongoDB connection settings and connection pool parameters.
​
mongodb.uri
string
required
MongoDB connection URI. Supports all standard MongoDB URI formats including authentication, replica sets, and connection options.Environment variable: ${ENV.MONGODB_URI}Example: mongodb://username:password@localhost:27017
​
mongodb.database
string
required
The name of the MongoDB database to use for Permission Mongo collections.Environment variable: ${ENV.MONGODB_DATABASE}
​
mongodb.max_pool_size
integer
default:"100"
Maximum number of connections in the MongoDB connection pool.
​
mongodb.min_pool_size
integer
default:"10"
Minimum number of connections to maintain in the MongoDB connection pool.

​
Example

mongodb:
  uri: "mongodb://127.0.0.1:27017"
  database: "permission_mongo"
  max_pool_size: 100
  min_pool_size: 10

​
Environment Variables

mongodb:
  uri: "${ENV.MONGODB_URI}"
  database: "${ENV.MONGODB_DATABASE}"

​
Redis Configuration

Configure Redis connection for caching policies, hierarchies, and schemas.
​
redis.url
string
required
Redis server URL in the format host:port or full Redis URI.Environment variable: ${ENV.REDIS_URL}
​
redis.password
string
Password for Redis authentication. Leave empty if no authentication is required.Environment variable: ${ENV.REDIS_PASSWORD}
​
redis.db
integer
default:"0"
Redis database number (0-15).
​
redis.pool_size
integer
default:"10"
Number of connections in the Redis connection pool.

​
Example

redis:
  url: "127.0.0.1:6379"
  password: ""
  db: 0
  pool_size: 10

​
Authentication Configuration

Configure JWT authentication settings for API access.
​
auth.jwt.algorithm
string
default:"RS256"
JWT signing algorithm. Supported values: RS256, RS384, RS512, HS256, HS384, HS512.
​
auth.jwt.public_key_file
string
Path to the public key file for RSA algorithms (RS256/RS384/RS512). Required when using RSA algorithms.
​
auth.jwt.issuer
string
Expected JWT issuer claim. Tokens with a different issuer will be rejected.

​
Example

auth:
  jwt:
    algorithm: "RS256"
    public_key_file: "/etc/permission-mongo/keys/public.pem"
    issuer: "permission-mongo"

​
Audit Configuration

Configure audit logging for all operations. Audit logs track create, read, update, and delete operations.
​
audit.log_reads
boolean
default:"false"
Whether to log read operations. Can generate high volume in read-heavy workloads.
​
audit.log_writes
boolean
default:"true"
Whether to log write operations (create, update, delete).
​
audit.log_failed
boolean
default:"true"
Whether to log failed operations (permission denied, validation errors).
​
audit.include_changes
boolean
default:"true"
Include before/after document snapshots in audit logs for update operations.

​
MongoDB Storage

​
audit.storage.mongodb.enabled
boolean
default:"true"
Store audit logs in MongoDB.
​
audit.storage.mongodb.collection
string
default:"_pm_audit"
MongoDB collection name for storing audit logs.
​
audit.storage.mongodb.ttl_days
integer
default:"90"
Number of days to retain audit logs before automatic deletion via TTL index.

​
Webhook Storage

​
audit.storage.webhook.enabled
boolean
default:"false"
Send audit logs to an external webhook URL.
​
audit.storage.webhook.url
string
Webhook URL to send audit logs to. Required when webhook is enabled.Environment variable: ${ENV.AUDIT_WEBHOOK_URL}
​
audit.storage.webhook.headers
object
Custom HTTP headers to include in webhook requests.
​
audit.storage.webhook.batch_size
integer
default:"100"
Number of audit log entries to batch before sending to webhook.
​
audit.storage.webhook.flush_interval_seconds
integer
default:"5"
Maximum time in seconds to wait before flushing batched audit logs.

​
Example

audit:
  log_reads: false
  log_writes: true
  log_failed: true
  include_changes: true
  storage:
    mongodb:
      enabled: true
      collection: "_pm_audit"
      ttl_days: 90
    webhook:
      enabled: true
      url: "${ENV.AUDIT_WEBHOOK_URL}"
      headers:
        Authorization: "Bearer ${ENV.WEBHOOK_SECRET}"
      batch_size: 100
      flush_interval_seconds: 5

​
Cache Configuration

Configure TTL (time-to-live) for different cache types. Permission Mongo caches policies, hierarchies, and schemas in Redis.
​
cache.policy_ttl_seconds
integer
default:"60"
TTL in seconds for cached policy configurations.
​
cache.hierarchy_ttl_seconds
integer
default:"300"
TTL in seconds for cached user hierarchy data.
​
cache.schema_ttl_seconds
integer
default:"60"
TTL in seconds for cached schema configurations.

​
Example

cache:
  policy_ttl_seconds: 60
  hierarchy_ttl_seconds: 300
  schema_ttl_seconds: 60

​
Versioning Configuration

Configure document version cleanup and archival settings.
​
versioning.cleanup_interval_hours
integer
default:"24"
Interval in hours between version cleanup operations that remove old versions.
​
versioning.archive.enabled
boolean
default:"false"
Enable archiving old versions to an external system before deletion.
​
versioning.archive.webhook
string
Webhook URL to send archived versions to.
​
versioning.archive.batch_size
integer
default:"1000"
Number of versions to archive in a single batch.
​
versioning.archive.before_delete
boolean
Whether to archive versions before deleting them.
​
versioning.archive.retry
integer
default:"3"
Number of retry attempts for failed archive operations.
​
versioning.archive.timeout_seconds
integer
default:"30"
Timeout in seconds for archive webhook requests.

​
Example

versioning:
  cleanup_interval_hours: 24
  archive:
    enabled: false
    webhook: "${ENV.ARCHIVE_WEBHOOK_URL}"
    batch_size: 1000
    before_delete: true
    retry: 3
    timeout_seconds: 30

​
Scalability Configuration

Configure resource limits to prevent abuse and ensure system stability.
​
scalability.max_concurrent_requests
integer
default:"10000"
Maximum number of concurrent HTTP requests the server will handle.
​
scalability.max_batch_size
integer
default:"1000"
Maximum number of documents in a single batch operation.
​
scalability.max_aggregation_stages
integer
default:"20"
Maximum number of stages in MongoDB aggregation pipelines.
​
scalability.max_result_size
integer
default:"10000"
Maximum number of documents returned in a single query result.
​
scalability.query_memory_limit_mb
integer
default:"100"
Memory limit in MB for individual query operations.

​
Example

scalability:
  max_concurrent_requests: 10000
  max_batch_size: 1000
  max_aggregation_stages: 20
  max_result_size: 10000
  query_memory_limit_mb: 100

​
Complete Example

version: "1.0"

server:
  host: "0.0.0.0"
  port: 8080
  read_timeout: "30s"
  write_timeout: "30s"

mongodb:
  uri: "${ENV.MONGODB_URI}"
  database: "permission_mongo"
  max_pool_size: 100
  min_pool_size: 10

redis:
  url: "${ENV.REDIS_URL}"
  password: "${ENV.REDIS_PASSWORD}"
  db: 0
  pool_size: 10

auth:
  jwt:
    algorithm: "RS256"
    public_key_file: "/etc/permission-mongo/keys/public.pem"
    issuer: "permission-mongo"

audit:
  log_reads: false
  log_writes: true
  log_failed: true
  include_changes: true
  storage:
    mongodb:
      enabled: true
      collection: "_pm_audit"
      ttl_days: 90
    webhook:
      enabled: true
      url: "${ENV.AUDIT_WEBHOOK_URL}"
      headers:
        Authorization: "Bearer ${ENV.WEBHOOK_SECRET}"
      batch_size: 100
      flush_interval_seconds: 5

cache:
  policy_ttl_seconds: 60
  hierarchy_ttl_seconds: 300
  schema_ttl_seconds: 60

versioning:
  cleanup_interval_hours: 24
  archive:
    enabled: false

scalability:
  max_concurrent_requests: 10000
  max_batch_size: 1000
  max_aggregation_stages: 20
  max_result_size: 10000
  query_memory_limit_mb: 100

​
Environment Variable Substitution

All configuration values support environment variable substitution using the ${ENV.VAR_NAME} syntax: 
mongodb:
  uri: "${ENV.MONGODB_URI}"
  database: "${ENV.MONGODB_DATABASE}"

redis:
  url: "${ENV.REDIS_URL}"
  password: "${ENV.REDIS_PASSWORD}"
Environment variables are substituted when the configuration file is loaded.

​
Loading Configuration

The server configuration is loaded at startup from the path specified via command-line flag: 
permission-mongo --config=/path/to/server.yml
Or using the PM_CONFIG environment variable: 
export PM_CONFIG=/path/to/server.yml
permission-mongo

Build docs developers (and LLMs) love

Get started for freeTalk to us