Cratopus icon
Launch Console

⚙️ Configuration Guide

Crate Community Edition (CE) is designed for simplicity and focuses on local, YAML-based configuration. This guide covers all aspects of configuring your Crate CE instance.

YAML Configuration

Each file in the configuration directory corresponds to an Organization. Files must be named with the config_ prefix followed by a valid UUID:

config_bc7e5f3a-8b1e-4b1a-9c1a-1a2b3c4d5e6f.yaml

Organization Schema

The YAML file follows the OrganizationConfig schema:

# Display name for the organization
name: "My Local Organization"

# List of domains managed by this organization
domains:
  - host: "api.local.crate.cc"
    details:
      # Routing policy
      routing:
        type: "round-robin"  # Options: "round-robin", "failover"
        destinations:
          - "http://backend-1:8080"
          - "http://backend-2:8081"
      
      # Security settings
      security:
        # Optional: Isolate admin routes on a dedicated subdomain
        admin_subdomain: "admin"
        # Optional: List of IP addresses/CIDR blocks allowed for admin routes
        ip_allowlist: ["127.0.0.1", "192.168.1.0/24"]

Routing Strategies

  • round-robin: Distributes incoming requests equally among all health-checked destinations.
  • failover: Sends all traffic to the first available destination; switches to the next only if the current one fails.

Environment Variables

Crate CE can be customized using the following environment variables:

Variable Description Default
SERVICE REQUIRED: The name of the service (must be gateway). -
ENVIRONMENT Operational environment (e.g., production, development). development
CODE_VERSION The version of the core binary. 1.0.0
CONFIG_STORAGE_DIR The directory where Crate CE looks for YAML files. /etc/crate/config
HTTP_PORT The primary port the Gateway listens on. 80
HTTPS_PORT The TLS port for the Gateway. 443
TRAFFIC_LOG_FILE Enable local traffic logging to a file (JSONL). false
TRAFFIC_LOG_PATH The destination path for traffic logs. ./traffic.jsonl

Configuration Directory Structure

A typical Crate CE configuration directory looks like this:

/etc/crate/config/
├── config_bc7e5f3a-8b1e-4b1a-9c1a-1a2b3c4d5e6f.yaml
├── config_123e4567-e89b-12d3-a456-426614174000.yaml
└── config_f47ac10b-58cc-4372-a567-0e02b2c3d479.yaml

Crate CE will automatically load and watch these files for changes. Adding, removing, or modifying these files will take effect immediately without a restart.

Next Steps