Bring up a minimal working environment first, then move database, cache, storage, and file-processing services to the level required by real usage. For the first deployment, start with the lightweight profile; for long-term multi-user usage, prefer PostgreSQL + Redis.

Before You Start#

DEEIX Chat deployment starts by clarifying three things: where the service runs, which public URLs browsers should use, and where data and files are persisted. Avoid maintaining the same value in multiple places. If environment variables override config.yaml, record the override source so later debugging stays clear.

git clone https://github.com/DEEIX-AI/DEEIX-Chat.gitcd DEEIX-Chat

Choose a Deployment Path#

The five paths cover trials, production-like single-node deployment, full local dependencies, separated frontend/backend hosting, and source development. Choose the path first, then copy the matching template. Mixing fields from different templates is not recommended.

1. Lightweight Install#

The lightweight install starts only the app container. Data is stored in SQLite, vector indexes use sqlite-vec, and cache uses in-process memory. This is the fastest way to evaluate the product, run demos, or host a small single-node setup. For long-term multi-user usage, migrate to PostgreSQL + Redis.

Prepare Configuration#

cp config.sqlite.example.yaml config.yaml

Before any public deployment, replace at least security.jwt_secret, security.data_encryption_key, server.public_api_base_url, server.public_web_base_url, and server.cors_allow_origin. You can generate secrets in the configuration guide.

Start the App#

docker compose -f docker-compose.sqlite.yml up -d

The default image is ghcr.io/deeix-ai/deeix-chat:latest. To use a local image or test a source build, override the image name.

DEEIX_CHAT_IMAGE=deeix-chat:local docker compose -f docker-compose.sqlite.yml up -d --build

Open the Service#

2. Standard Deployment#

The standard deployment starts only the application container. Use it when PostgreSQL, Redis, object storage, or platform infrastructure already exists. Database and Redis addresses must be resolvable and reachable from inside the container. If they run on the Docker host, host.docker.internal is usually the right hostname.

Prepare Configuration#

cp config.example.yaml config.yaml

Check Connection Settings#

Start the App#

docker compose up -d

The default docker-compose.yml does not start PostgreSQL or Redis. Keep matching Compose environment variables empty unless you intentionally want them to override config.yaml; otherwise the effective config source becomes hard to audit.

3. Full Deployment#

The full deployment starts App, PostgreSQL, and Redis on one machine. It is closer to the production dependency model than the lightweight profile, works better for long-running single-node usage, and is easier to migrate toward external database, Redis, or managed cloud services later.

Prepare Configuration#

cp config.full.example.yaml config.yaml

Before public deployment, replace security secrets, public URLs, CORS, trusted proxies, PostgreSQL password, Redis password, and storage settings.

Start the Full Stack#

docker compose -f docker-compose.full.yml up -d

docker-compose.full.yml injects POSTGRES_DSN, REDIS_ADDR, and REDIS_PASSWORD through environment variables. Environment variables have higher priority than config.yaml, so these values override database and Redis settings in the config file. This is intentional so the app container connects to the Compose-managed services.

Check Dependencies#

docker compose -f docker-compose.full.yml psdocker compose -f docker-compose.full.yml logs postgresdocker compose -f docker-compose.full.yml logs redis

If the app fails to start, check whether PostgreSQL finished initialization, whether the Redis password matches, whether config.yaml is mounted, and whether Compose environment variables override the expected fields.

4. Separated Deployment#

Use separated deployment when frontend and backend are exposed through different public origins. For example, the web app runs at https://chat.example.com and the API runs at https://api.example.com. This path requires build variables, CORS, public URLs, and CDN route fallback to align. Read the configuration guide before production release.

Align Public URLs#

Build the Frontend#

cd frontendpnpm installNEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm build

When publishing frontend/out, the CDN or static server must support route fallback, for example /chat to /chat/index.html. API, health check, and Swagger paths should bypass CDN cache and forward complete headers, request bodies, and response statuses.

Verify After Deployment#

curl https://api.example.com/healthzcurl https://chat.example.com

If the page loads but API calls fail, the usual causes are NEXT_PUBLIC_API_BASE_URL, cors_allow_origin, or reverse-proxy routes not matching. Frontend build variables are embedded into static assets, so changes require rebuilding the frontend.

5. Local Development#

Local development is for source changes, frontend/backend debugging, and UI interaction checks. It is not the shortest trial path. The default config connects to local PostgreSQL and Redis, so make sure those dependencies are running first.

Backend#

cp config.example.yaml config.yamlcd backendmake run

The backend listens on http://localhost:8080 by default, and Swagger is available at http://localhost:8080/swagger/index.html.

Frontend#

cd frontendpnpm installcp .env.example .env.localpnpm dev

The local frontend usually points to the backend development service.

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080

Startup Checks#

After startup, verify health, container status, config mount, and logs. The commands below use the lightweight profile. For the standard profile, omit -f docker-compose.sqlite.yml; for the full profile, replace it with -f docker-compose.full.yml.

curl http://localhost:8080/healthzdocker compose -f docker-compose.sqlite.yml psdocker compose -f docker-compose.sqlite.yml exec app ls -l /app/config.yamldocker compose -f docker-compose.sqlite.yml logs app

First Login#

If the database does not contain a superadmin account, the backend creates the initial administrator on first startup and prints the initial password only once. Do not store the initial password in the config file, and do not keep using initial credentials for real operation.

Optional File Processing Services#

The base deployment does not require document parsing or OCR services. Start these optional services only when the matching capability is enabled in the admin console or configuration. They are usually related to file extraction, OCR, and RAG indexing, so bring up the base application first and add them gradually.

docker compose -f docker/tika/docker-compose.yml up -ddocker compose -f docker/tesseract/docker-compose.yml up -d --builddocker compose -f docker/docling/docker-compose.yml up -d --build

These services join deeix-chat-network. Start one root deployment first, or create the network manually.

docker network create deeix-chat-network

Next Steps#

After login, finish runtime business configuration before opening the service to real users. Models, upstreams, routes, pricing, file policies, RAG, and MCP tools belong in the admin console rather than hard-coded deployment config.