{"id":29353688,"url":"https://github.com/zyrakq/step-ca-companion","last_synced_at":"2026-05-18T02:36:22.094Z","repository":{"id":303662096,"uuid":"1016267954","full_name":"zyrakq/step-ca-companion","owner":"zyrakq","description":"step-ca integration for nginxproxy/acme-companion with automatic trust and ACME certificates","archived":false,"fork":false,"pushed_at":"2025-08-02T21:22:28.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-02T23:31:06.079Z","etag":null,"topics":["acme-companion","docker","nginx-proxy","ssl-certificates","step-ca"],"latest_commit_sha":null,"homepage":"https://github.com/zyrakq/step-ca-companion/pkgs/container/step-ca-companion","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zyrakq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-08T18:38:20.000Z","updated_at":"2025-08-02T21:20:07.000Z","dependencies_parsed_at":"2025-07-08T19:49:18.528Z","dependency_job_id":"808a6650-57a8-4de5-88a0-d90333c97d55","html_url":"https://github.com/zyrakq/step-ca-companion","commit_stats":null,"previous_names":["zyrakq/step-ca-companion"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zyrakq/step-ca-companion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyrakq%2Fstep-ca-companion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyrakq%2Fstep-ca-companion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyrakq%2Fstep-ca-companion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyrakq%2Fstep-ca-companion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zyrakq","download_url":"https://codeload.github.com/zyrakq/step-ca-companion/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyrakq%2Fstep-ca-companion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33162688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acme-companion","docker","nginx-proxy","ssl-certificates","step-ca"],"created_at":"2025-07-09T02:08:51.025Z","updated_at":"2026-05-18T02:36:22.088Z","avatar_url":"https://github.com/zyrakq.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔐 Step-CA Companion (nginxproxy/acme-companion)\n\nCustom image based on `nginxproxy/acme-companion` with automatic step-ca integration through step CLI bootstrap.\n\n## 📋 Description\n\nThis image extends the standard `nginxproxy/acme-companion` with automatic trust establishment to step-ca, enabling the use of a private CA for issuing ACME certificates.\n\n## 🔗 Dependencies\n\nThis companion is designed to work with:\n\n- **[nginx-proxy](https://github.com/nginx-proxy/nginx-proxy)**: Reverse proxy with HTTP-01 challenge support\n- **[nginxproxy/acme-companion](https://github.com/nginx-proxy/acme-companion)**: Base ACME client functionality\n- **step-ca**: Private certificate authority with ACME provisioner\n\n## 🌐 DNS Requirements\n\nFor proper operation, you need:\n\n- **DNS Server**: Configure your DNS server to redirect your chosen top-level domain to the host address\n- **DNS Client**: Configure containers to use your DNS server\n- **nginx-proxy**: Must listen on ports 80 and 443 of the host for HTTP-01 challenge validation\n\n### Docker-based DNS Servers\n\n- **[zyrakq/docker-unbound](https://github.com/zyrakq/docker-unbound)**: Unbound DNS server\n- **[zyrakq/unbound-stack](https://github.com/zyrakq/unbound-stack)**: Unbound configuration example\n- **[jpillora/docker-dnsmasq](https://github.com/jpillora/docker-dnsmasq)**: DNSMasq DNS server\n\nExample DNS configuration:\n\n```ini\n*.local -\u003e 192.168.1.100  # Your Docker host IP\n```\n\n## ✨ Key Features\n\n- **🔄 Automatic Discovery**: Automatically finds step-ca container\n- **🛡️ Automatic Trust**: Establishes trust through step CLI bootstrap\n- **📦 Full Compatibility**: Maintains all nginxproxy/acme-companion functionality\n- **🔧 Flexible Configuration**: Supports manual and automatic configuration\n- **🐳 Container Trust**: Automatic trust certificate installation in Docker containers\n- **⚡ Event-Driven**: Real-time monitoring of Docker container events\n\n## 🚀 Usage\n\n### Basic Certificate Generation for Docker Containers\n\n```yaml\nservices:\n  my-app:\n    image: nginx:alpine\n    environment:\n      - VIRTUAL_HOST=myapp.local          # For nginx-proxy\n      - LETSENCRYPT_HOST=myapp.local          # For ACME certificate\n      - LETSENCRYPT_EMAIL=admin@myapp.local   # Email (optional)\n    networks:\n      - step-ca-network\n```\n\n### Trust Certificate Installation in Docker Containers\n\nFor Docker containers that need to communicate with other containers via HTTPS:\n\n```yaml\nservices:\n  # Client that periodically checks server health\n  health-checker:\n    image: alpine:3.18\n    environment:\n      - STEP_CA_TRUST=true\n      - STEP_CA_TRUST_RESTART=true  # Restart after certificate installation\n    command: |\n      sh -c \"\n        apk add --no-cache curl \u0026\u0026\n        while true; do\n          echo \\\"[$(date)] Checking server health...\\\"\n          if curl -s https://api.local/health \u003e /dev/null 2\u003e\u00261; then\n            echo \\\"[$(date)] ✅ Server is healthy\\\"\n          else\n            echo \\\"[$(date)] ❌ Server health check failed - SSL verification error\\\"\n          fi\n          sleep 30\n        done\n      \"\n    networks:\n      - step-ca-network\n    depends_on:\n      - api-server\n  \n  # API server with SSL certificate\n  api-server:\n    image: nginx:alpine\n    environment:\n      - VIRTUAL_HOST=api.local\n      - LETSENCRYPT_HOST=api.local\n    networks:\n      - step-ca-network\n```\n\n### Complete Stack Example with nginx-proxy\n\nSince step-companion is designed to work exclusively with nginx-proxy and step-ca, here's a complete docker-compose example:\n\n```yaml\nversion: '3.8'\n\nservices:\n  # Step-CA Certificate Authority\n  step-ca:\n    container_name: step-ca\n    image: smallstep/step-ca:latest\n    environment:\n      - DOCKER_STEPCA_INIT_NAME=Local Step CA\n      - DOCKER_STEPCA_INIT_DNS_NAMES=step-ca,localhost\n      - DOCKER_STEPCA_INIT_ACME=true\n      - DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true\n    volumes:\n      - step-ca-data:/home/step\n    networks:\n      - step-ca-proxy-tier\n    ports:\n      - \"9000:9000\"\n    healthcheck:\n      test: [\"CMD\", \"step\", \"ca\", \"health\", \"--ca-url=https://localhost:9000\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 10s\n\n  step-ca-proxy:\n    container_name: step-ca-proxy\n    image: nginxproxy/nginx-proxy:latest\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n    labels:\n      com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxy: \"true\"\n    volumes:\n      - step-ca-vhost:/etc/nginx/vhost.d\n      - step-ca-certs:/etc/nginx/certs:ro\n      - step-ca-html:/usr/share/nginx/html\n      - /var/run/docker.sock:/tmp/docker.sock:ro\n    networks:\n      - step-ca-proxy-tier\n      - step-ca-network\n\n  step-ca-companion:\n    container_name: step-ca-companion\n    build:\n      context: ./src/step-ca-companion/app\n      dockerfile: Dockerfile\n    environment:\n      ACME_CA_URI: https://step-ca:9000/acme/acme/directory\n      ACME_STAGING: false\n      STEP_CA_CONTAINER_NAME: step-ca\n      STEP_CA_BOOTSTRAP_TIMEOUT: 300\n      CRON_ENABLED: true\n      CRON_SCHEDULE: \"0 */6 * * *\"\n      CRON_LOG_LEVEL: 2\n    restart: always\n    depends_on:\n      step-ca:\n        condition: service_healthy\n      step-ca-proxy:\n        condition: service_started\n    volumes:\n      - step-ca-acme:/etc/acme.sh\n      - step-ca-vhost:/etc/nginx/vhost.d\n      - step-ca-certs:/etc/nginx/certs\n      - step-ca-html:/usr/share/nginx/html\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n    networks:\n      - step-ca-proxy-tier\n\n    \n\n  # Example application with automatic SSL\n  my-app:\n    image: nginx:alpine\n    environment:\n      - VIRTUAL_HOST=myapp.local\n      - LETSENCRYPT_HOST=myapp.local\n    networks:\n      - step-ca-network\n\nvolumes:\n  step-ca-data:\n    name: step-ca-data\n  step-ca-acme:\n    name: step-ca-acme\n  step-ca-vhost:\n    name: step-ca-vhost\n  step-ca-certs:\n    name: step-ca-certs\n  step-ca-html:\n    name: step-ca-html\n\nnetworks:\n  step-ca-proxy-tier:\n    name: step-ca-proxy-tier\n    driver: bridge\n  step-ca-network:\n    name: step-ca-network\n    driver: bridge\n```\n\n## 🌐 Remote Context DNS Configuration\n\nWhen deploying on a remote host (accessed via Docker context), where the certificate authority needs to resolve virtual addresses and issue certificates for them, you may need to deploy a simplified DNS server that only serves Docker containers, not the host client.\n\n### When DNS Configuration is Required\n\n- **Remote Docker context**: Working with Docker on a different host\n- **Virtual domain resolution**: step-ca needs to resolve domains like `*.local` for certificate validation\n- **Container-only DNS**: Simplified setup where only Docker containers use the DNS server\n- **No host DNS setup**: When you don't want to configure DNS client on the host itself\n\n### When DNS Configuration is NOT Required\n\n- **Local deployment**: step-ca running on the same host as the client\n- **Host DNS configured**: You have already configured DNS client on the host\n- **External DNS server**: You have a proper DNS server infrastructure\n\n### Complete Stack Example with DNS Server\n\n```yaml\nversion: '3.8'\n\nservices:\n  # DNS Server for Docker containers (remote context only)\n  step-ca-unbound:\n    container_name: step-ca-unbound\n    image: ghcr.io/zyrakq/unbound:latest\n    ports:\n      - \"${DNS_SERVER}:53:53/udp\"\n      - \"${DNS_SERVER}:53:53/tcp\"\n    environment:\n      ACCESS_CONTROL_CUSTOM: ${ACCESS_CONTROL_CUSTOM}\n      LOCAL_DOMAINS: ${LOCAL_DOMAINS}\n      BLOCK_PRIVATE: ${BLOCK_PRIVATE:-false}\n    restart: unless-stopped\n    networks:\n      - step-ca-proxy-tier\n\n  # Step-CA Certificate Authority\n  step-ca:\n    container_name: step-ca\n    image: smallstep/step-ca:latest\n    environment:\n      - DOCKER_STEPCA_INIT_NAME=Local Step CA\n      - DOCKER_STEPCA_INIT_DNS_NAMES=step-ca,localhost\n      - DOCKER_STEPCA_INIT_ACME=true\n      - DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true\n    volumes:\n      - step-ca-data:/home/step\n    networks:\n      - step-ca-proxy-tier\n    ports:\n      - \"9000:9000\"\n    healthcheck:\n      test: [\"CMD\", \"step\", \"ca\", \"health\", \"--ca-url=https://localhost:9000\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 10s\n    depends_on:\n      - step-ca-unbound\n\n  step-ca-proxy:\n    container_name: step-ca-proxy\n    image: nginxproxy/nginx-proxy:latest\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n    labels:\n      com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxy: \"true\"\n    volumes:\n      - step-ca-vhost:/etc/nginx/vhost.d\n      - step-ca-certs:/etc/nginx/certs:ro\n      - step-ca-html:/usr/share/nginx/html\n      - /var/run/docker.sock:/tmp/docker.sock:ro\n    networks:\n      - step-ca-proxy-tier\n      - step-ca-network\n    depends_on:\n      - step-ca-unbound\n\n  step-ca-companion:\n    container_name: step-ca-companion\n    build:\n      context: ./src/step-ca-companion/app\n      dockerfile: Dockerfile\n    environment:\n      ACME_CA_URI: https://step-ca:9000/acme/acme/directory\n      ACME_STAGING: false\n      STEP_CA_CONTAINER_NAME: step-ca\n      STEP_CA_BOOTSTRAP_TIMEOUT: 300\n      CRON_ENABLED: true\n      CRON_SCHEDULE: \"0 */6 * * *\"\n      CRON_LOG_LEVEL: 2\n    restart: always\n    depends_on:\n      step-ca:\n        condition: service_healthy\n      step-ca-proxy:\n        condition: service_started\n    volumes:\n      - step-ca-acme:/etc/acme.sh\n      - step-ca-vhost:/etc/nginx/vhost.d\n      - step-ca-certs:/etc/nginx/certs\n      - step-ca-html:/usr/share/nginx/html\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n    networks:\n      - step-ca-proxy-tier\n    depends_on:\n      - step-ca-unbound\n\n  # Example application with automatic SSL\n  my-app:\n    image: nginx:alpine\n    environment:\n      - VIRTUAL_HOST=myapp.local\n      - LETSENCRYPT_HOST=myapp.local\n    networks:\n      - step-ca-network\n    depends_on:\n      - step-ca-unbound\n\nvolumes:\n  step-ca-data:\n    name: step-ca-data\n  step-ca-acme:\n    name: step-ca-acme\n  step-ca-vhost:\n    name: step-ca-vhost\n  step-ca-certs:\n    name: step-ca-certs\n  step-ca-html:\n    name: step-ca-html\n\nnetworks:\n  step-ca-proxy-tier:\n    name: step-ca-proxy-tier\n    driver: bridge\n  step-ca-network:\n    name: step-ca-network\n    driver: bridge\n```\n\n### Environment Variables for DNS Configuration\n\n```bash\n# DNS server IP (usually the Docker host IP)\nDNS_SERVER=192.168.1.100\n\n# Access control for DNS queries\nACCESS_CONTROL_CUSTOM=192.168.0.0/16 allow, 172.16.0.0/12 allow, 10.0.0.0/8 allow\n\n# Local domains to resolve to the host\nLOCAL_DOMAINS=*.local 192.168.1.100\n\n# Block private IP ranges (optional)\nBLOCK_PRIVATE=false\n```\n\n### Docker Host DNS Configuration\n\nFor remote deployment, configure Docker daemon on the host in `/etc/docker/daemon.json`:\n\n```json\n{\n  \"dns\": [\"192.168.1.100\", \"8.8.8.8\", \"8.8.4.4\"]\n}\n```\n\n**Important**: When `/etc/docker/daemon.json` is properly configured, you don't need to specify DNS settings for individual containers in docker-compose.yml. The daemon configuration applies to all containers automatically.\n\n### Systemd Service Configuration\n\nIf the Docker systemd service doesn't include the config file parameter, add it manually:\n\n```ini\n[Service]\nExecStart=/usr/bin/dockerd --config-file=/etc/docker/daemon.json\n```\n\nAfter configuration changes, restart Docker daemon:\n\n```bash\nsudo systemctl restart docker\n```\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TB\n    A[step-ca] --\u003e B[Custom acme-companion]\n    B --\u003e C[nginx-proxy]\n    B --\u003e D[Docker Containers]\n    \n    subgraph \"Custom acme-companion\"\n        E[step CLI bootstrap]\n        F[Trust certificate installation]\n        G[ACME operations]\n        H[Docker events monitoring]\n        I[Container trust setup]\n        E --\u003e F\n        F --\u003e G\n        H --\u003e I\n        I --\u003e D\n    end\n```\n\n## ⚙️ Environment Variables\n\n### Main (acme-companion)\n\n- `ACME_CA_URI`: step-ca ACME server URI\n- `ACME_STAGING`: Staging mode (false for production)\n\n### step-ca integration (optional)\n\n- `STEP_CA_CONTAINER_NAME`: step-ca container name (auto-detection)\n- `STEP_CA_URL`: step-ca URL (auto-detection)\n- `STEP_CA_FINGERPRINT`: step-ca fingerprint (auto-detection)\n- `STEP_CA_BOOTSTRAP_TIMEOUT`: Bootstrap timeout in seconds (300)\n\n### Cron Configuration\n\n- `CRON_ENABLED`: Enable/disable periodic trust certificate processing (default: `true`)\n- `CRON_SCHEDULE`: Cron schedule for trust certificate processing (default: `0 */6 * * *`)\n- `CRON_LOG_LEVEL`: Cron daemon log level (default: `2`)\n\n### Container Environment Variables\n\nFor containers that need trust certificates:\n\n- `STEP_CA_TRUST`: Set to `true` to install step-ca trust certificate bundle\n- `STEP_CA_TRUST_RESTART`: Set to `true` to restart container after certificate installation\n\n## 🔍 Automatic step-ca Discovery\n\n### Discovery Priorities\n\n1. **Docker Labels**: `com.smallstep.step-ca`\n2. **Environment Variable**: `STEP_CA_CONTAINER_NAME`\n3. **Auto-detection**: By environment variables, port 9000, name\n\n### Parameter Retrieval Methods\n\n- **URL**: Formed from discovered container name\n- **Fingerprint**: Docker exec → API fallback\n\n### Initialization Process\n\n1. step-ca container discovery\n2. URL and fingerprint retrieval\n3. step CLI bootstrap with trust establishment\n4. Trust certificate monitor startup (Docker events)\n5. Standard acme-companion startup\n6. Automatic trust installation for containers with `STEP_CA_TRUST=true`\n\n## 📊 Logging\n\n```bash\n# View bootstrap logs\ndocker logs step-ca-companion | grep BOOTSTRAP\n\n# View discovery logs\ndocker logs step-ca-companion | grep \"step-ca container\"\n\n# Full logs\ndocker logs -f step-ca-companion\n```\n\n## 🔧 Debugging\n\n### Trust Verification\n\n```bash\n# Inside container\ndocker exec step-ca-companion curl -s https://step-ca:9000/health\n\n# Check fingerprint\ndocker exec step-ca-companion step certificate fingerprint /home/step/certs/root_ca.crt\n\n# Check trust installation logs\ndocker logs step-ca-companion | grep TRUST-\n```\n\n### Manual Configuration\n\n```yaml\nenvironment:\n  STEP_CA_URL: https://step-ca:9000\n  STEP_CA_FINGERPRINT: \"your-fingerprint-here\"\n```\n\n## 🐳 Container Trust Certificate Installation\n\nFor automatic installation of step-ca trust certificates in Docker containers:\n\n### Basic Usage\n\n```yaml\nservices:\n  my-app:\n    image: nginx:alpine\n    environment:\n      STEP_CA_TRUST: \"true\"         # Enables automatic trust certificate installation\n      STEP_CA_TRUST_RESTART: \"true\" # Restart container after certificate installation\n    networks:\n      - step-ca-network\n```\n\n### Certificate Bundle Details\n\nThe trust certificate installation now includes both root and intermediate certificates:\n\n- **Root Certificate**: `/home/step/certs/root_ca.crt` from step-ca container\n- **Intermediate Certificate**: `/home/step/certs/intermediate_ca.crt` from step-ca container\n- **Bundle**: Combined certificate file containing both certificates for complete PKI trust chain\n\n### Container Restart Option\n\nSome applications may require a restart to properly load new trust certificates. Use `STEP_CA_TRUST_RESTART=true` to automatically restart the container after certificate installation:\n\n```yaml\nservices:\n  # Application that needs restart after certificate installation\n  secure-app:\n    image: myapp:latest\n    environment:\n      STEP_CA_TRUST: \"true\"\n      STEP_CA_TRUST_RESTART: \"true\"  # Container will be restarted after certificate installation\n    networks:\n      - step-ca-network\n```\n\n### Supported Container Operating Systems\n\n| OS | Package Manager | Certificate Path | Update Command |\n|---|---|---|---|\n| Ubuntu/Debian | `apt-get` | `/usr/local/share/ca-certificates/` | `update-ca-certificates` |\n| Alpine | `apk` | `/usr/local/share/ca-certificates/` | `update-ca-certificates` |\n| CentOS/RHEL | `yum` | `/etc/pki/ca-trust/source/anchors/` | `update-ca-trust` |\n| Fedora | `dnf` | `/etc/pki/ca-trust/source/anchors/` | `update-ca-trust` |\n| Arch Linux | `pacman` | `/etc/ca-certificates/trust-source/anchors/` | `trust extract-compat` |\n\n### How It Works\n\n1. **Event Monitoring**: Monitors Docker container start events\n2. **Environment Check**: Detects containers with `STEP_CA_TRUST=true`\n3. **OS Detection**: Automatically detects container operating system\n4. **Certificate Retrieval**: Gets step-ca root and intermediate certificates bundle\n5. **Package Installation**: Installs `ca-certificates` package if needed\n6. **Trust Installation**: Copies certificate bundle and updates trust store\n7. **Container Restart**: Optionally restarts container if `STEP_CA_TRUST_RESTART=true`\n8. **Verification**: Tests HTTPS connectivity to step-ca\n\n### Example: Microservices with Trust\n\n```yaml\nservices:\n  api-gateway:\n    image: nginx:alpine\n    environment:\n      VIRTUAL_HOST: api.local\n      STEP_CA_TRUST: \"true\"  # Can make HTTPS requests to other services\n    networks:\n      - step-ca-network\n  \n  user-service:\n    image: node:18-alpine\n    environment:\n      STEP_CA_TRUST: \"true\"  # Can make HTTPS requests to step-ca signed services\n    networks:\n      - step-ca-network\n  \n  database-client:\n    image: postgres:15-alpine\n    environment:\n      STEP_CA_TRUST: \"true\"  # Can connect to SSL-enabled databases\n    networks:\n      - step-ca-network\n```\n\n## ⏰ Cron Configuration\n\nThe step-ca-companion includes a configurable cron job for periodic trust certificate processing. This ensures that containers with `STEP_CA_TRUST=true` maintain valid trust certificates even if they were missed during initial startup or docker-gen monitoring.\n\n### Basic Configuration\n\n```yaml\nservices:\n  step-ca-companion:\n    environment:\n      CRON_ENABLED: true              # Enable periodic processing\n      CRON_SCHEDULE: \"0 */6 * * *\"    # Every 6 hours (default)\n      CRON_LOG_LEVEL: 2               # Cron daemon log level\n```\n\n### Custom Schedules\n\n```yaml\n# Every 12 hours\nCRON_SCHEDULE: \"0 */12 * * *\"\n\n# Daily at 2 AM\nCRON_SCHEDULE: \"0 2 * * *\"\n\n# Every 30 minutes (for testing)\nCRON_SCHEDULE: \"*/30 * * * *\"\n\n# Disable cron completely\nCRON_ENABLED: false\n```\n\n### Cron Schedule Format\n\nThe `CRON_SCHEDULE` variable uses standard cron format:\n\n```sh\n┌───────────── minute (0 - 59)\n│ ┌─────────── hour (0 - 23)\n│ │ ┌───────── day of month (1 - 31)\n│ │ │ ┌─────── month (1 - 12)\n│ │ │ │ ┌───── day of week (0 - 6) (Sunday to Saturday)\n│ │ │ │ │\n* * * * *\n```\n\n### Monitoring Cron Jobs\n\n```bash\n# Check cron configuration\ndocker exec step-ca-companion crontab -l\n\n# View cron setup logs\ndocker logs step-ca-companion | grep CRON-SETUP\n\n# View cron execution logs\ndocker exec step-ca-companion tail -f /var/log/trust-processor.log\n```\n\n## �️ Host Trust Certificate Installation\n\nFor automatic installation of step-ca certificate on the host system with multi-user Docker context support:\n\n### Automatic Installation with systemd (Recommended)\n\n```bash\n# Install user systemd integration (no sudo required)\n./scripts/install-systemd-integration.sh\n\n# Check status\n./scripts/install-systemd-integration.sh status\n\n# View logs\njournalctl --user -u step-ca-monitor.service -f\n\n# Remove integration\n./scripts/install-systemd-integration.sh uninstall\n```\n\n**User Systemd Service Features:**\n\n- **User-specific monitoring**: Monitors Docker contexts for current user only\n- **Multi-level monitoring**: Docker Events + Context Changes (10s) + Periodic Container Check (30s)\n- **User-context certificates**: Certificates named `step-ca-bundle-\u003cuser\u003e-\u003ccontext\u003e`\n- **Group-based permissions**: Uses `step-ca-certs` group for secure certificate management\n- **Cross-platform support**: Works on Ubuntu, Debian, Arch Linux, Fedora, RHEL\n\n### One-time Installation (Alternative)\n\n```bash\n# Automatic installation (uses current user and Docker context)\n./scripts/install-host-trust.sh\n\n# With custom user name\nCERT_USER=admin ./scripts/install-host-trust.sh\n\n# With custom container name\nSTEP_CA_CONTAINER_NAME=my-step-ca ./scripts/install-host-trust.sh\n\n# Install for specific context\ndocker context use production \u0026\u0026 ./scripts/install-host-trust.sh\n```\n\n### Multi-User Docker Context Support\n\n- **User-context naming**: Certificates are named `step-ca-bundle-\u003cuser\u003e-\u003ccontext\u003e`\n- **Multiple users and contexts**: Different users and contexts can coexist without conflicts\n- **Automatic switching**: systemd integration detects context changes for all users\n- **User isolation**: Each user-context combination maintains its own certificate\n\n### Requirements\n\n- Docker installed and running\n- step-ca container running\n- Supported Linux distribution (Ubuntu, Debian, Arch Linux, Fedora, RHEL, CentOS)\n- systemd with user service support (for automatic updates)\n- sudo privileges (only for group setup and certificate installation)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyrakq%2Fstep-ca-companion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzyrakq%2Fstep-ca-companion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyrakq%2Fstep-ca-companion/lists"}