> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# BRMS overview

> Self-hosted business rules management system with visual editor and REST API.

The GoRules BRMS is a complete business rules management system that provides a visual editor for creating and managing decision models, version control, release management, and REST API for rule evaluation.

<CardGroup cols={2}>
  <Card title="Docker Image" icon="docker" href="https://hub.docker.com/r/gorules/brms">
    Available on Docker Hub: `gorules/brms`
  </Card>

  <Card title="License Portal" icon="key" href="https://portal.gorules.io">
    Obtain your license key
  </Card>
</CardGroup>

## When to use BRMS

**Choose BRMS when:**

* Business users need to create and edit rules without code changes
* You need version control and audit trails for rule changes
* Multiple environments (dev, staging, prod) require release management
* You want a web-based UI for rule authoring and testing

**Consider alternatives when:**

* You only need to evaluate rules (use [Agent](/developers/deployment/agent/overview) or [embedded SDK](/developers/deployment/embedded))
* Rules are managed entirely in code

## Architecture

```mermaid theme={null}
flowchart TB
    users["Business Users"] --> brms
    brms["GoRules BRMS<br />(Web UI + API)"]
    postgres["PostgreSQL"]
    storage["Object Storage<br />(S3, GCS, Azure)"]
    agent["GoRules Agent"]
    apps["Your Applications"]

    brms --> postgres
    brms --> storage
    agent --> storage
    apps --> agent
```

## Requirements

| Component | Requirement                                                  |
| --------- | ------------------------------------------------------------ |
| Database  | PostgreSQL 12+                                               |
| Runtime   | Docker (Linux x86\_64)                                       |
| License   | From [portal.gorules.io](https://portal.gorules.io)          |
| Network   | Outbound HTTPS to `portal.gorules.io` for license validation |

## Environment variables

### Required

```shell theme={null}
DB_HOST=your-database-host
DB_USER=gorules
DB_PASSWORD=your-password
DB_NAME=gorules
LICENSE_KEY=your-license-key           # From portal.gorules.io
```

### Database

```shell theme={null}
DB_HOST=db.example.com                  # Required
DB_PORT=5432                            # Default: 5432
DB_USER=gorules                         # Required
DB_PASSWORD=your-password               # Required
DB_NAME=gorules                         # Required
DB_CREDENTIALS_PROVIDER=default         # Options: default, aws-iam, azure-iam
```

### Database SSL

```shell theme={null}
DB_SSL_DISABLED=false                   # Default: false
DB_REJECT_UNAUTHORIZED=true             # Default: true
DB_SSL_CA=<base64-ca-certificate>       # CA certificate
DB_SSL_CERT=<base64-client-cert>        # Client certificate
DB_SSL_KEY=<base64-client-key>          # Client private key
DB_SSL_ADVANCED=<json-ssl-options>      # Advanced SSL config
```

### Database options

```shell theme={null}
DB_MIGRATE=true                         # Run migrations on startup (default: true)
DB_SYNCHRONIZE=false                    # Auto-sync schema - dev only! (default: false)
DB_LOGGING=false                        # Log SQL queries (default: false)
```

<Warning>
  Never enable `DB_SYNCHRONIZE` in production. It can cause data loss.
</Warning>

### Application

```shell theme={null}
APP_NAME=GoRules                        # Display name in UI
APP_URL=https://rules.example.com       # Public URL of the application
API_BASE_URL=/api                       # API base path (default: /api)
HOME_URI=/                              # Default landing page (default: /)
LICENSE_KEY=your-license-key            # Required
LICENSE_MODE=online                     # Options: online, offline (default: online)
LOG_LEVEL=info                          # Options: debug, info, warn, error (default: info)
```

### HTTP server

```shell theme={null}
HTTP_HOST=0.0.0.0                       # Default: 0.0.0.0
HTTP_PORT=80                            # Default: 80
HTTP_SSL_KEY=<base64-ssl-key>           # SSL private key
HTTP_SSL_CERT=<base64-ssl-cert>         # SSL certificate
```

### Security

```shell theme={null}
COOKIE_SECRET=your-32-byte-secret       # Session cookie encryption
SESSION_DURATION_MINUTES=1440           # Session timeout (default: 1440 = 24h)
HASH_SECRET=your-hash-secret            # Internal hashing
RELEASE_ZIP_PASSWORD=your-password      # Password-protect release downloads
```

Generate a secure secret:

```bash theme={null}
openssl rand -hex 32
```

### CORS

```shell theme={null}
CORS_ALLOW_ORIGIN=https://example.com   # Allowed origins (comma-separated, supports regex)
```

Example with multiple origins and regex:

```shell theme={null}
CORS_ALLOW_ORIGIN=https://gorules.io,REGEX:\.gorules\.io$
```

### Email (SMTP)

```shell theme={null}
EMAIL_ENABLED=true                      # Enable email sending (default: true)
EMAIL_HOST=smtp.example.com             # SMTP server hostname
EMAIL_PORT=587                          # SMTP server port
EMAIL_SECURE=false                      # Use TLS/SSL (default: false)
EMAIL_AUTH_USER=your-username           # SMTP username
EMAIL_AUTH_PASS=your-password           # SMTP password
EMAIL_FROM=noreply@example.com          # Sender address (default: noreply@gorules.io)
```

### Email TLS options

```shell theme={null}
EMAIL_TLS_REJECT_UNAUTHORIZED=true      # Reject invalid certificates
EMAIL_TLS_SERVER_NAME=smtp.example.com  # TLS server name
EMAIL_TLS_SKIP_SERVER_IDENTITY=false    # Skip server identity verification
```

### OAuth providers

### Secrets encryption

See [Secrets management](/developers/deployment/brms/secrets-management) for detailed setup.

### SSO (OIDC)

See [SSO configuration](/developers/deployment/brms/sso) for detailed setup.

```shell theme={null}
SSO_OAUTH2_PROVIDER=oidc                # Options: azure, okta, oidc
SSO_OAUTH2_CLIENT_ID=your-client-id
SSO_OAUTH2_CLIENT_SECRET=your-secret    # Not required for PKCE
SSO_OAUTH2_ISSUER=https://your-idp.com
SSO_OAUTH2_JWKS_URI=https://your-idp.com/.well-known/jwks.json
SSO_OAUTH2_SCOPES=openid email profile  # Default: openid email profile
SSO_OAUTH2_REDIRECT_URI=/_callback      # Default: /_callback
SSO_OAUTH2_AUTH_URL=https://...         # Authorization endpoint (legacy providers)
SSO_OAUTH2_TOKEN_URL=https://...        # Token endpoint (legacy providers)
SSO_OAUTH2_AUTHORITY_URL=https://...    # Authority URL
```

### SSO group mapping

```shell theme={null}
SSO_OAUTH2_GROUPS_MAPPING=group1->admin,group2->member
SSO_OAUTH2_CUSTOM_CLAIM_NAME=groups     # JWT claim containing groups (default: groups)
SSO_OAUTH2_ROLES_MAPPING_ENABLED=false  # Enable fine-grained role mapping (default: false)
SSO_OAUTH2_IDENTITY_TOKEN_SOURCE=access_token  # Options: access_token, id_token
```

### LLM integration

```shell theme={null}
LLM_PROVIDER=anthropic                  # Options: anthropic, google, openai, amazon-bedrock, google-vertex, azure-openai
LLM_MODEL=claude-sonnet-4-6             # Model name
LLM_API_KEY=your-api-key
LLM_TEMPERATURE=0.4                     # Applies to Gemini/Google providers only (default: 0.4)
LLM_CONTEXT_WINDOW=200000               # Context window size in tokens (provider default)
LLM_MAX_OUTPUT_TOKENS=32000             # Maximum tokens per response (default: 32000)
LLM_THINKING_LEVEL=medium               # Extended thinking: high, medium (default: medium)
```

## Health probes

**Path:** `/api/health`
**Port:** `80`

Recommended probe configuration:

| Setting       | Value      |
| ------------- | ---------- |
| Initial delay | 10 seconds |
| Period        | 10 seconds |

## API reference

See the [API reference](/api-reference/introduction) for endpoint documentation.