Skip to content

Common configuration

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

Core environment variables

Set these in the main Easy8 .env file:

EASY_JWT_SECRET=change-this-to-a-strong-shared-secret
EASY_AI_CHAIN_IMAGE=registry.example.com/easy-ai-chain:tag
EASY_AI_CHROMA_IMAGE=registry.example.com/chromadb:tag
  • EASY_JWT_SECRET must be identical in Easy8 and Chain. A deprecated EASY_AI_JWT_SECRET is still accepted by Chain; use EASY_JWT_SECRET in new installations.
  • EASY_AI_CHAIN_IMAGE is required for the AI package deployment.
  • EASY_AI_CHROMA_IMAGE is the image of the chroma service in docker-compose_easy_ai.yml. Use the value from your package.

For the services each product needs, see Prerequisites. The AI package shares one redis service between the AI services and Easy8.

Easy8-to-Chain URLs

In the standard package deployment these variables have working defaults, so you usually do not set them:

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
  • EASY_AI_PUBLIC_URL is the address the browser uses. If you do not set it, Easy8 uses <protocol>://<host name>/ai/chain, taking the host name from the setting Host name and path in the Easy8 settings (/settings).
  • EASY_AI_CHAIN_URL is the address Easy8 uses for server-to-server calls. If you do not set it, Easy8 builds it from EASY_AI_CHAIN_HOST and EASY_AI_CHAIN_PORT, which default to chain and 8000.

The two URLs differ in a standard deployment: the public URL goes through your reverse proxy, the internal one stays inside Docker.

After you clone an environment

If you create a test instance by copying the production database, Host name and path can still point to production. Browser requests from the test instance then go to the production /ai/chain URL, and AI activation or assistant actions fail when the reverse proxy is configured only for the test URL.

After cloning, check that Host name and path and the effective EASY_AI_PUBLIC_URL match the 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 your own or an 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 your 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

Browsers reach Chain through /ai/chain. Add this rule to the server block of your Easy8 site:

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;
}
  • 3320 is the host port exposed by the package compose for the chain service.
  • the chain container starts with --root-path /ai/chain/, so keep the public /ai/chain prefix

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