Quick Start #

This page takes you from a clean machine to a running DEEIX Chat instance you can sign in to. Start with the lightweight profile, then move to PostgreSQL and Redis before you open it to real users.

Before you start #

Item	Requirement
Container install	Docker Engine with Docker Compose v2
Local development	Node.js 20.9+, pnpm 10.17.0, Go 1.26.8, and a local PostgreSQL and Redis
Config file	`deploy/config.yaml`, copied from a profile template
Secrets	Replace `security.jwt_secret` and `security.data_encryption_key` before any public deployment

terminal

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

Choose an installation profile #

All Docker assets live in deploy/. You can copy that directory to a server without the application source. Run every compose command from inside deploy/.

Profile	Use case	Template	Compose file	Dependencies
Lightweight	Local evaluation, personal use, small single-node deployments	`deploy/config.sqlite.example.yaml`	`deploy/docker-compose.sqlite.yml`	App only, SQLite + sqlite-vec + in-memory cache
Default	PostgreSQL and Redis already exist	`deploy/config.example.yaml`	`deploy/docker-compose.yml`	App only
Full	Single machine running app, PostgreSQL, and Redis	`deploy/config.full.example.yaml`	`deploy/docker-compose.full.yml`	App, PostgreSQL, Redis

1. Lightweight installation (SQLite)#

The lightweight profile starts only the app container. Data and vector indexes use SQLite, and the cache runs in process. Use it to evaluate the product or host a small single-node instance.

terminal

cd deploycp config.sqlite.example.yaml config.yamldocker compose -f docker-compose.sqlite.yml up -d

Open the service:

Service	URL
Web app	`http://localhost:8080`
Liveness	`http://localhost:8080/healthz`
Readiness	`http://localhost:8080/readyz`
Version	`http://localhost:8080/api/v1/version`
Swagger	`http://localhost:8080/swagger/index.html`

The template sets app.env: dev, so Swagger is enabled. Before a public deployment, set app.env: prod, replace the two secrets, and set the public URLs and CORS origins.

SQLite + memory cache is single-process only. Use PostgreSQL + Redis for multi-node or high-concurrency deployments.

Use a local image #

The default image is ghcr.io/deeix-ai/deeix-chat:latest. Build a local image from the repository root, then select it:

terminal

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

2. Default installation (external PostgreSQL + Redis)#

Use this profile when PostgreSQL and Redis are managed outside the compose stack. Set the addresses to values the container can reach. If the services run on the Docker host, host.docker.internal is usually the right hostname.

terminal

cd deploycp config.example.yaml config.yaml# Edit database.postgres.dsn, database.redis.*, and the public URLs.docker compose up -d

docker-compose.yml starts only the app container. Do not add matching environment values unless you intend them to override config.yaml.

3. Full installation (PostgreSQL + Redis containers)#

Use this profile to start the app, PostgreSQL, and Redis together on one machine.

terminal

cd deploycp config.full.example.yaml config.yamldocker compose -f docker-compose.full.yml up -d

docker-compose.full.yml sets POSTGRES_DSN, REDIS_ADDR, REDIS_USERNAME, and REDIS_PASSWORD in the app container. These environment variables override the matching values in config.yaml so the app connects to the bundled services.

Check the containers:

terminal

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

4. Local development #

Local development runs the frontend and backend from the repository. The default config connects to a local PostgreSQL and Redis, so start those first.

terminal

cp deploy/config.example.yaml config.yamlpnpm installcp apps/web/.env.example apps/web/.env.localmake dev

make dev starts the workspace dev tasks. To run only the API and the web app, run make api and make web in two terminals. make help lists every target.

Service	URL
Frontend	`http://localhost:3000`
API	`http://localhost:8080`
Liveness	`http://localhost:8080/healthz`
Readiness	`http://localhost:8080/readyz`
Version	`http://localhost:8080/api/v1/version`
Swagger	`http://localhost:8080/swagger/index.html`

Confirm apps/web/.env.local points at the backend:

env

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080

5. Separated deployment #

Use separated deployment when the frontend and API have different public origins, for example https://chat.example.com and https://api.example.com. Align the frontend build variable, the backend public URLs, and CORS, then read Configuration before release.

terminal

pnpm installNEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm --filter @deeix/web build

The static output is apps/web/out. Serve it from a CDN or static server, or point server.frontend_dist_dir at it so the Go service serves it.

Startup checks #

terminal

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

Check	Expected result	Look at first when it fails
Liveness	`{"status":"ok",...}`	Config parsing, port conflicts
Readiness	Ready response	Database and cache connections
Config mount	`/app/config.yaml` exists	Working directory, volume path, permissions
Startup logs	No migration or initialization errors	Database version, secret length, environment overrides

If the database has no superadmin, the backend creates one on first startup and prints the password once.

Item	Value
Initial username	`admin`
Initial password	Search the backend startup logs for `bootstrap superadmin created` and read the `password` field.
First sign-in	The onboarding requires a new username and password, and offers 2FA setup.
After onboarding	Sign in again with the new credentials, then enter the admin console.

The onboarding walks through these steps:

Welcome and interface language.
Account: set the new administrator username and password.
Two-factor authentication: bind an authenticator, or skip.
Theme preset.
Personalization: timezone and color mode.
Ready: review recovery codes if 2FA was enabled, then sign in again.

If a superadmin already exists, the service does not create or print an initial password again. Credentials are not managed through config.yaml.

Optional file processing services #

Document extraction and OCR are optional. Start a service only when you enable the matching capability in the admin console. Each service attaches to the external deeix-chat-network, so start an application profile first or create the network:

terminal

docker network create deeix-chat-network

Run from inside deploy/:

terminal

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

Service	URL	Purpose
Tika	`http://127.0.0.1:9998`	Document text extraction
Tesseract OCR	`http://127.0.0.1:8004/ocr`	OCR service
Docling	`http://127.0.0.1:8005/ocr`	Document and OCR extraction

deploy/services/rapidocr has a Dockerfile and entrypoint but no compose file.

Desktop app #

If you do not want to run a server, the desktop client bundles the Go backend. Install it from GitHub Releases, then choose Use on this computer for local mode or Connect to a server for an existing deployment. See Desktop App.

Next steps #

Configure the runtime business settings in the admin console before you invite users.

Area	Action
Upstreams and models	Add upstream channels, platform models, and route bindings.
Files and retrieval	Confirm storage, extraction, OCR, embedding, and retrieval settings.
Login and security	Check public URLs, CORS, trusted proxies, registration, and 2FA.
Billing	Choose the billing mode and configure pricing, plans, payments, and webhooks.
Operations	Check logs, audit events, backups, GeoIP, and OpenTelemetry.