i2incommon/comanage-registry-pe-develop repository overview

⁠COmanage Registry PE Container

This repository provides a containerized setup for running COmanage Registry with Apache, PHP-FPM, and supporting configuration for TLS and Shibboleth SP integration.

• Environment variables control most runtime behavior (URL path, DB, email, TLS, bootstrap admin, etc.).
• For the full list of supported environment variables, defaults, and examples, see:
  • Environment Variables Guide⁠

⁠Quick Start

1. Build the image

• docker compose build

1. Configure secrets and environment

• Ensure your secrets are available (e.g., HTTPS cert/key, DB password, email password).
• Set environment variables in docker-compose.yml as needed.

Example environment section:

services:
  comanage-registry:
    environment:
      # Role
      - COMANAGE_ROLE=web

      # General
      - COMANAGE_DEBUG=1
      - COMANAGE_REGISTRY_CONTAINER=1
      - ENV=dev
      - USERTOKEN=team-x

      # URL/Apache
      - COMANAGE_REGISTRY_URL_PATH=registry-pe
      - COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN=registry.example.org
      - HTTPS_CERT_FILE=/run/secrets/https_cert_file
      - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file

      # Admin bootstrap
      - COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=Registry
      - COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=Admin
      - COMANAGE_REGISTRY_ADMIN_USERNAME=registry.admin
      - COMANAGE_REGISTRY_SECURITY_SALT_FILE=/run/secrets/security_salt

      # Database
      - COMANAGE_REGISTRY_DATABASE_DRIVER=Cake\Database\Driver\Postgres
      - COMANAGE_REGISTRY_DATABASE_HOST=database
      - COMANAGE_REGISTRY_DATABASE=registry
      - COMANAGE_REGISTRY_DATABASE_USER=registry_user
      - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/db_password
      - COMANAGE_REGISTRY_DATABASE_PORT=5432
      - COMANAGE_REGISTRY_DATABASE_PERSISTENT=false

      # Email
      - COMANAGE_REGISTRY_EMAIL_TRANSPORT=Smtp
      - COMANAGE_REGISTRY_EMAIL_HOST=smtp.example.org
      - COMANAGE_REGISTRY_EMAIL_PORT=587
      - COMANAGE_REGISTRY_EMAIL_TLS=true
      - [email protected]
      - COMANAGE_REGISTRY_EMAIL_ACCOUNT_PASSWORD_FILE=/run/secrets/email_password
      - [email protected]
      - COMANAGE_REGISTRY_EMAIL_FROM_NAME=COmanage Registry

1. Start the stack

• docker compose up -d

1. Access the application

• https://YOUR_HOSTNAME/ (redirects to the URL path you configured, e.g., /registry-pe/)

⁠Configuration

• URL Path (routing and on-disk symlink):

  • COMANAGE_REGISTRY_URL_PATH controls the path segment (defaults to registry). At runtime, the container renders Apache config and ensures a webroot symlink matching this path exists under /var/www/html.

• Logging (stdout/stderr vs file logs):

  • Set COMANAGE_REGISTRY_CONTAINER=1 to route application logs to stdout/stderr inside the container; when not set, logs are written to files under the application’s logs directory.

• Full list of environment variables:

  • See the Environment Variables Guide⁠

⁠Logging

The container supports three logging modes. Choose based on how you want to consume logs (files vs container stdout/stderr).

1. Default mode (no special env var set)

• Behavior:
  • Only the error output is emitted; debug output is not created.
  • Errors are read from the application’s error.log and printed out.
• Levels included by default:
  • warning, error, critical, alert, emergency
• Message structure:
  • comanage_registry;error.log;ENV;USERTOKEN;MESSAGE
• Example:
  • comanage_registry;error.log;dev;team-x;[2025-11-06 14:22:31] ERROR: Database connection failed

1. Debug mode (enable with COMANAGE_DEBUG=1)

• Behavior:
  • Both error.log and debug.log are emitted.
• Levels by file:
  • error.log: warning, error, critical, alert, emergency
  • debug.log: notice, info, debug
• Message structure:
  • comanage_registry;error.log;ENV;USERTOKEN;MESSAGE
  • comanage_registry;debug.log;ENV;USERTOKEN;MESSAGE
• Examples:
  • comanage_registry;error.log;dev;team-x;[2025-11-06 14:25:10] WARNING: Job queue is behind by 3m
  • comanage_registry;debug.log;dev;team-x;[2025-11-06 14:25:11] INFO: Queued job id=123 for processing

1. Container-native mode (enable with COMANAGE_REGISTRY_CONTAINER=1)

• Behavior:
  • No log files are created in the container; logs are written directly to the container streams.
• Stream mapping:
  • stdout: notice, info, debug (and auxiliary scopes like queries, trace)
  • stderr: warning, error, critical, alert, emergency
• How to view:
  • docker logs -f <container_or_service_name>
• Tip:
  • This mode is recommended for orchestrators and centralized log collectors.

Notes:

• You can set COMANAGE_DEBUG=1 and COMANAGE_REGISTRY_CONTAINER=1 together: debug/info/notice go to stdout, while warnings and higher go to stderr.
• The ENV and USERTOKEN values (if provided) appear in the emitted line prefix in file-based modes to help correlate logs across environments/users.

⁠Roles: Web and Cron

This image supports two runtime roles, selected via the COMANAGE_ROLE environment variable.

• Web (default)

  • Purpose: Serve COmanage Registry over Apache HTTPD.
  • Entry: The container prepares configuration (URL path, TLS, DB/email unless skipped) and then execs Apache in the foreground.
  • Typical env:
    • COMANAGE_ROLE=web (or omit; web is the default)
    • COMANAGE_REGISTRY_URL_PATH (default: registry)
    • COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN (FQDN shown in logs/config)
    • HTTPS_CERT_FILE, HTTPS_PRIVKEY_FILE (optional; if provided, copied into Apache paths)
    • Database and Email envs (see Environment Variables Guide)
  • Ports: Usually 80 and 443.

• Cron

  • Purpose: Run scheduled COmanage Registry tasks (eg, job queue).
  • Entry: The container prepares configuration, deploys a crontab, starts a lightweight syslogd, then execs crond in the foreground.
  • Typical env:
    • COMANAGE_ROLE=cron
    • COMANAGE_REGISTRY_CRONTAB (optional; default: /srv/comanage-registry/local/crontab)
    • COMANAGE_REGISTRY_CRON_USER (optional; default: apache)
    • Database and Email envs (same as web so CLI tasks can access services)
  • Ports: None exposed for cron-only service.

Example docker-compose snippet:

services:
  comanage-cron:
    image: i2incommon/comanage-registry:latest
    environment:
      # Role
      - COMANAGE_ROLE=cron

      # General
      - COMANAGE_DEBUG=1
      - COMANAGE_REGISTRY_CONTAINER=1

      # Optional: override crontab path or cron user
      # - COMANAGE_REGISTRY_CRONTAB=/srv/comanage-registry/local/crontab
      # - COMANAGE_REGISTRY_CRON_USER=apache

      # Database (should match the web service)
      - COMANAGE_REGISTRY_DATABASE_DRIVER=Cake\Database\Driver\Postgres
      - COMANAGE_REGISTRY_DATABASE_HOST=database
      - COMANAGE_REGISTRY_DATABASE=registry
      - COMANAGE_REGISTRY_DATABASE_USER=registry_user
      - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/db_password
      - COMANAGE_REGISTRY_DATABASE_PORT=5432
      - COMANAGE_REGISTRY_DATABASE_PERSISTENT=false

      # Email (same config as web, so cron jobs can send mail)
      - COMANAGE_REGISTRY_EMAIL_TRANSPORT=Smtp
      - COMANAGE_REGISTRY_EMAIL_HOST=smtp.example.org
      - COMANAGE_REGISTRY_EMAIL_PORT=587
      - COMANAGE_REGISTRY_EMAIL_TLS=true
      - [email protected]
      - COMANAGE_REGISTRY_EMAIL_ACCOUNT_PASSWORD_FILE=/run/secrets/email_password
      - [email protected]
      - COMANAGE_REGISTRY_EMAIL_FROM_NAME=COmanage Registry

• Check logs (container stdout):
  • docker logs -f comanage-registry

⁠License

See LICENSE⁠ for details.