i2incommon/comanage-registry-pe 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

      # Authentication (Optional: defaults to shibboleth)
      # - COMANAGE_REGISTRY_AUTH_TYPE=basic
      # - COMANAGE_REGISTRY_BASIC_AUTH_PASSWORDS_FILE=/run/secrets/basic_auth_passwords
      # - COMANAGE_REGISTRY_ADMIN_PASSWORD=password

      # 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/)

⁠Basic Authentication (Local Development)

For local development and testing, you can use HTTP Basic Authentication instead of Shibboleth.

1. Enable Basic Auth: Set COMANAGE_REGISTRY_AUTH_TYPE=basic in your environment.
2. Create Passwords File (Optional): If you want to use a specific passwords file, create it using htpasswd (e.g., in the secrets/ directory):

   mkdir -p secrets
   htpasswd -c ./secrets/passwords admin
   

   Copy
   Note: If no passwords file is provided, the container will automatically create one with the user COMANAGE_REGISTRY_ADMIN_USERNAME and password COMANAGE_REGISTRY_ADMIN_PASSWORD (defaults to "password").
3. Configure Secrets: If using your own passwords file, add it to your docker-compose.yml secrets section and map it to the service:

   services:
     comanage-registry:
       environment:
         - COMANAGE_REGISTRY_AUTH_TYPE=basic
         - COMANAGE_REGISTRY_BASIC_AUTH_PASSWORDS_FILE=/run/secrets/basic_auth_passwords
       secrets:
         - basic_auth_passwords
   
   secrets:
     basic_auth_passwords:
       file: ./secrets/passwords
   

   Copy
4. Login: Access the registry at your configured registry path followed by /auth/login (e.g., https://registry.example.org/registry-pe/auth/login). The default configuration for local development requires the user specified by COMANAGE_REGISTRY_ADMIN_USERNAME (default: registry.admin).

⁠Initial Registry Setup

COmanage Registry requires an initial setup to bootstrap the database and create the first administrator account.

⁠Automated Setup

The container automatically runs the setup command (bin/cake setup) on the first start if it detects that the database has not been initialized. It uses the following environment variables:

• COMANAGE_REGISTRY_ADMIN_GIVEN_NAME (Default: Registry)
• COMANAGE_REGISTRY_ADMIN_FAMILY_NAME (Default: Admin)
• COMANAGE_REGISTRY_ADMIN_USERNAME (Default: registry.admin)

To skip the automated setup (e.g., when connecting to an existing database), set COMANAGE_REGISTRY_SKIP_SETUP=1.

⁠Manual Setup

If you need to run the setup command manually (e.g., to re-run or use different parameters), use docker compose exec:

docker compose exec comanage-registry /srv/comanage-registry/app/bin/cake setup \
  --admin-given-name "Admin" \
  --admin-family-name "User" \
  --admin-username "admin"

⁠Configuration

⁠Environment Variables

The setup uses environment variables for both the Docker Compose orchestration (interpolation) and the container runtime.

1. Automatic .env File: Docker Compose automatically loads a file named .env in the project root. This file is used to resolve placeholders like ${VARIABLE} in the docker-compose.yml.

   • Note: Ensure variables are in KEY=VALUE format (no export keyword).

2. Custom Environment Files: To use a different environment file (e.g., dev.env), you must use the --env-file flag before the subcommand (like up or build).

   • Incorrect: docker compose up --env-file dev.env
   • Correct: docker compose --env-file dev.env up
   • With Service: docker compose --env-file dev.env up comanage-registry-basic
   • With Build & Service: docker compose --env-file dev.env up --build comanage-registry-basic

   Placement is important: The flag must come before the subcommand for it to affect the interpolation of the docker-compose.yml file.

   Note on Priority: If a variable is already exported in your host shell, it will override the value in your environment file. If you see unexpected values in your container, run unset $(env | grep COMANAGE_REGISTRY_PE | cut -d= -f1) in your terminal first.

3. Container Runtime (env_file): The docker-compose.yml is configured to also load .env directly into the container's environment. This allows you to add variables to the container without explicitly mapping them in the environment: section.

• 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.