Skip to content

Common Configuration

These settings apply to all on-premises Easy8 AI installations.

Core environment variables

Set these in the main Easy8 deployment .env file:

EASY_JWT_SECRET=change-this-to-a-strong-shared-secret
EASY_AI_CHAIN_IMAGE=registry.example.com/easy-ai-chain:tag

Notes:

  • EASY_JWT_SECRET must be identical in Easy8 and Chain.
  • EASY_AI_CHAIN_IMAGE is required for the AI package deployment.

Required compose services by product

Easy8 AI Basic

Required runtime services:

  • app
  • chain
  • celery
  • redis
  • LLM provider

Not required:

  • chroma
  • embeddings provider

Easy8 AI Knowledge assistant PRO / Easy8 AI Helpdesk

Required runtime services:

  • app
  • chain
  • celery
  • redis
  • chroma
  • embeddings provider
  • LLM provider

Redis is shared between the AI services in the package deployment.

Internal Easy8-to-Chain settings

In the standard package deployment, these values have working defaults and usually do not need to be set manually:

EASY_AI_CHAIN_HOST=chain
EASY_AI_CHAIN_PORT=8000
EASY_AI_CHAIN_URL=http://chain:8000
EASY_AI_PUBLIC_URL=https://your.easy.host/ai/chain

Notes:

  • EASY_AI_PUBLIC_URL is used by the browser.
  • If EASY_AI_PUBLIC_URL is not set, Easy8 defaults it to <Easy8 app URL>/ai/chain.
  • The Easy8 app URL is built from ::Setting.protocol and ::Setting.host_name.
  • ::Setting.host_name is the URL or host name of the main Easy8 application.
  • EASY_AI_CHAIN_URL is used by Easy8 for server-to-server calls.
  • If EASY_AI_CHAIN_URL is not set, Easy8 defaults it to http://chain:8000.
  • EASY_AI_CHAIN_HOST defaults to chain.
  • EASY_AI_CHAIN_PORT defaults to 8000.
  • EASY_AI_CHAIN_HOST and EASY_AI_CHAIN_PORT are the internal service coordinates used to build EASY_AI_CHAIN_URL when needed.
  • EASY_AI_JWT_SECRET is still accepted by the chain as a deprecated fallback, but new installations should use EASY_JWT_SECRET.

Public vs internal access

Use these values for different purposes:

  • EASY_AI_PUBLIC_URL for browser access from the Easy8 frontend
  • EASY_AI_CHAIN_URL for server-to-server calls from the Easy8 application

Do not assume the public URL and internal URL are always the same. In standard package deployments, they usually differ.

For standard package deployments:

  • the public URL usually resolves automatically from the main Easy8 application URL plus /ai/chain
  • the internal chain URL usually resolves automatically to http://chain:8000

Important:

  • In Easy8, if EASY_AI_PUBLIC_URL is not set, it defaults from the application setting Host name and path on /settings.
  • If a customer creates a test instance by copying the production database, this setting may still point to the production URL.
  • In that case, browser-based Easy8 AI requests can be sent to the production /ai/chain URL instead of the test environment.
  • If the reverse proxy is only configured on the test URL, AI activation or assistant actions in the test environment can fail because requests are sent to the wrong host.
  • After cloning an environment, always verify that Host name and path and the effective EASY_AI_PUBLIC_URL match the actual URL of that environment.

Custom CA certificates for self-hosted AI endpoints

If LLM_URL or EMBEDDINGS_URL uses HTTPS with a certificate signed by a customer or internal CA, the CA bundle must be available inside the chain and celery containers.

The standard AI package mounts the persistent chain_data volume to /data in both containers. Store the CA bundle there, for example:

docker compose exec chain mkdir -p /data/certs
docker compose cp ./customer-ca.pem chain:/data/certs/customer-ca.pem

Then set these variables in the Easy8 deployment .env file or extra environment file used by the AI package:

REQUESTS_CA_BUNDLE=/data/certs/customer-ca.pem
SSL_CERT_FILE=/data/certs/customer-ca.pem
CURL_CA_BUNDLE=/data/certs/customer-ca.pem

Recreate the containers that need the new environment:

docker compose up -d --force-recreate chain celery

Verify from inside the chain container:

docker compose exec chain test -f /data/certs/customer-ca.pem
docker compose exec chain /app/.venv/bin/python -c 'import requests; r=requests.get("https://your-llm-host/v1/models", timeout=5); print(r.status_code)'
docker compose exec chain /app/.venv/bin/python -c 'import httpx; r=httpx.get("https://your-llm-host/v1/models", timeout=5); print(r.status_code)'

If the Docker volume is removed, for example with docker compose down -v, the certificate file must be copied again.

Custom vLLM served model aliases

Chain discovers self-hosted vLLM models by calling <LLM_URL>/v1/models. The returned model id must either match a supported Chain model name or be explicitly mapped to a supported Chain LLM ID.

Use VLLM_MODEL_ALIASES when the customer vLLM endpoint exposes a deployment-specific served model id, for example custom-gemma-31b, but the underlying model should use a known Chain profile such as gemma-4-31b:

LLM_URL=https://your-vllm-host
VLLM_MODEL_ALIASES=custom-gemma-31b=gemma-4-31b
DEFAULT_LLM_ID=gemma-4-31b

VLLM_MODEL_ALIASES is a comma-separated list of SERVED_MODEL_ID=CHAIN_LLM_ID pairs. Chain registers the provider under CHAIN_LLM_ID, but still sends the original SERVED_MODEL_ID to vLLM in OpenAI-compatible API requests.

Examples:

VLLM_MODEL_ALIASES=custom-gemma-31b=gemma-4-31b
VLLM_MODEL_ALIASES=customer-gemma=gemma-4-31b,customer-ministral=ministral-3-14b

The CHAIN_LLM_ID value must already be supported by Chain. If the mapping points to an unknown Chain LLM ID, the vLLM host is ignored and Chain logs a configuration error.

Nginx configuration

Easy8 clients access the chain through /ai/chain.

Use a reverse proxy rule equivalent to:

location /ai/chain {
  rewrite ^/ai/chain(/.*)$ $1 break;
  proxy_set_header Host $host:$server_port;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_pass http://127.0.0.1:3320;
}

Notes:

  • 3320 is the host port exposed by the package compose for the chain service.
  • the chain container is started with --root-path /ai/chain/, so the public /ai/chain prefix must be preserved

Optional variables

Use these when needed:

EASY_AI_CORS_ALLOWED_ORIGINS=https://your.easy.host

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=...
LANGCHAIN_PROJECT=customer-name

Package deployment reminder

The standard package should include docker-compose_easy_ai.yml, which adds:

  • chain
  • chroma
  • celery
  • shared redis

The installed scenario then decides which of those services are actually needed by the enabled Easy8 AI product.