Rapid deployment

This page brings you a complete Aivory stack with Docker Compose in 5 minutes: PostgreSQL, Redis, Qdrant, built-in code sandbox, and a simultaneous server front-end SPA and /api The rear end. app Container (both of the same source, no domain name or CORS configuration required).

The entire stack is described by a compose file that includes the following services:

The Service	The mirror	Role of
postgres	postgres:16-alpine	Relational storage: user, conversation, knowledge base, usage and so on
redis	redis:7-alpine	Caching, limit flow counters, cross-process stop streaming output pub/sub
qdrant	qdrant/qdrant:v1.12.4	RAG Vector Recovery
sandbox	ghcr.io/hjxwz123/aivory-sandbox-sidecar	built-in code execution sandbox, only available on the internal network
app	ghcr.io/hjxwz123/aivory-app	Single container servicing SPA and /api

Do you want to run a full stack?

Aivory's backend is automatically selected by environmental variables: with PostgreSQL, use built-in SQLite, with Redis, use process cache, with Qdrant, inject RAG backwards into the whole. The SQLite model This page describes the recommended full production deployments.

Requirements in advance

The project	Requested
Docker Engine	installed and can operate normally (docker info No reporting errors
Docker Compose	v2(docker compose The book, not the old version. docker-compose)
specification of machine.	2 Core CPU + 4 GB of memory
The Port	Hosts 80 ports free (changeable, see below)
The Disc	Databases, vectors, and upload files are permanent in the native, reserved according to usage.

Sandbox requires a Docker socket

built-in code sandbox by hanging /var/run/docker.sock The isolated container is derived from each session on the host, so the host must be able to run Docker directly (not for hosted container platforms without a Docker custody process). app the visit.

Step 1: Get the code

git clone https://github.com/hjxwz123/Aivory.git
cd Aivory/deploy

All related documents are available. deploy/ In the catalogue: docker-compose.prod.yml 和 .env.example。

Step 2: Create and edit .env

cp .env.example .env

.env 中** must be modified ** Only three of them, the rest can be kept by default. Three of them retaining positioning values can lead to boot failure or serious security issues:

# 生成三个强随机值
openssl rand -hex 24   # 用作 POSTGRES_PASSWORD
openssl rand -hex 24   # 用作 REDIS_PASSWORD
openssl rand -hex 32   # 用作 JWT_SECRET

varied	Requested	Explained
POSTGRES_PASSWORD	must be	PostgreSQL password. compose refuses to start directly when not set
REDIS_PASSWORD	must be	Redis password. compose refuses to start directly when not set
JWT_SECRET	Minimum length of 32 characters.	Issuing an API key for a login token.Aivory detects a positioning or over-short API key in a production environment ** refused to start. **

JWT_SECRET Once leaked, all accounts are handed over.

Please use. openssl rand -hex 32 Generate, do not use predictable strings. at the same time note: replace JWT_SECRET All registered sessions will be invalidated.

API Key for the model server (Anthropic / OpenAI / Gemini, etc.)** is not available .env In the configuration**, they are present in the channel table of the database, and are added in the admin console after deployment is completed, see First operating configuration。

Step 3: Starting

Method one, pull a pre-built mirror image (recommended from the GitHub Container Registry):

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Method 2, local build from the source code (when the code is modified, or the official mirroring does not cover your CPU architecture):

docker compose -f docker-compose.prod.yml up -d --build

The same compose file supports two ways

app The service is simultaneously image: 和 build:: When pre-built mirrors are present locally, Compose prioritizes mirrors or returns to local builds. Database schema is created by automatic migration when the application is launched, and no SQL needs to be executed manually.

Step 4: Verification

docker compose -f docker-compose.prod.yml ps

5 services are expected: postgres、redis is in healthy, qdrant、app is in running, sandbox When you start for the first time, you need to first pull the sandbox runtime mirror, the health check reserves a 120-second start window, and you can wait a little to turn into healthy。

Then request the first page. app Inside the container. 8787 Port, compose by default maps it to the host. 80 The Port:

curl -sI http://localhost

Return to HTTP/1.1 200 And the content for the SPA page is successfully deployed if you change the port mapping to another (e.g. 8080:8787 Replace the port in the command.

What about 80 ports?

Port mapping does not follow environmental variables, directly edit docker-compose.prod.yml 中 app of service. ports The paragraph, take "80:8787" On the left side (for example). "8080:8787" on the right. 8787 Monitor the port inside the container, do not change it.

Step 5: Open the site and go to first-run setup

Visit the browser. http://<你的服务器 IP 或域名> Newly deployed without any users, the page automatically goes to first-run setup: the first account you create immediately becomes an administrator. First operating configuration。

The Dragon Order.

The following command blocks are completed from scratch: clone, generate an API key, write .env Pull the mirror image, start. Suitable for directly sticking on a new machine:

git clone https://github.com/hjxwz123/Aivory.git \
  && cd Aivory/deploy \
  && cp .env.example .env \
  && sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 24)|" .env \
  && sed -i "s|^REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -hex 24)|" .env \
  && sed -i "s|^JWT_SECRET=.*|JWT_SECRET=$(openssl rand -hex 32)|" .env \
  && docker compose -f docker-compose.prod.yml pull \
  && docker compose -f docker-compose.prod.yml up -d \
  && docker compose -f docker-compose.prod.yml ps

Save the .env

The above command writes the random API key directly. deploy/.env This file is equivalent to the key string you deploy, please include a backup and do not submit to the public warehouse.

.env.example Variables by section

Press below .env.example The grouping in line by line explains that each variable should not be changed.

Source of Mirror

varied	The default value	Should not change.
IMAGE_OWNER	hjxwz123	You change your account only when you fork the warehouse and publish a mirror image using your own GHCR naming space.
IMAGE_TAG	latest	Generally unchanged.If you need to lock the version, change it to the corresponding mirror label, avoid latest Navigated

Network and Cross-Domestic

varied	The default value	Should not change.
ALLOWED_ORIGINS	Not Set Up (Comment Status)	** Stay unavailable ** Single container deployment in SPA and /api The same source, no cross-domain; only needed when you split the front end to a different origin than the API. The reverse proxy

Attention: No WEB_PORT 或 PUBLIC_ORIGIN The host port changes in the compose file; the domain name does not need to be configured, which host is accessed by the container, which host can be used, and multiple domains can be pointed at the same time.

PostgreSQL

varied	The default value	Should not change.
POSTGRES_USER	aivory	No need to change.
POSTGRES_DB	aivory	No need to change.
POSTGRES_PASSWORD	Position Value	** must change **, openssl rand -hex 24

Redis

varied	The default value	Should not change.
REDIS_PASSWORD	Position Value	** must change **, openssl rand -hex 24

Qdrant

varied	The default value	Should not change.
QDRANT_URL	http://qdrant:6333	No need to change. Cover only when pointing to an external Qdrant cluster
QDRANT_API_KEY	空	Unchanged when vacant. qdrant Services and app Share the same built-in API key, open box for use; Qdrant does not publish any host ports, only internets are available. openssl rand -hex 24 covered

Certified

varied	The default value	Should not change.
JWT_SECRET	Position Value	** must change **, openssl rand -hex 32 at least 32 characters, otherwise the production environment will refuse to start

Data Directory and Backup

varied	The default value	Should not change.
DATA_DIR	./data	Depending on the disc planning. host path, binding hanging to the container /app/data to store user upload documents and generate products, ** must be included. **
BACKUP_DIR	/app/data/backups	No need to change.In-container path, admin console generates full ZIP storage migration asynchronously, corresponding to the host. DATA_DIR/backups
MAX_BACKUP_BYTES	21474836480(20 GiB)	Unchanged by admin console ** imported ** The upper limit of the size of the backup, the full volume of packets containing vector data may be large, and the time limit can be increased.

Data for databases, Redis, and Qdrant are named respectively. pgdata、redisdata、qdrantdata See backup tactics. Backup and Migration。

Demonstrated model

varied	The default value	Should not change.
ENABLE_MOCK_PROVIDER	false	can be selected. true Injected a built-in demo channel, no real API Key is needed to end-to-end conversation, suitable for first verification of deployment; after adding real channel in the admin console false

Internet search (optional)

varied	The default value	Should not change.
SEARCH_PROVIDER	空	Optional. search backend type: serper / brave Required SEARCH_API_KEY; searxng Required SEARCH_BASE_URL No need for key.
SEARCH_API_KEY	空	随 SEARCH_PROVIDER and determined
SEARCH_BASE_URL	空	仅 searxng Requirements of the back

These three can also be deployed after configuration in admin console online. .env The values are only at the end of the starting period and can be left empty first.

embedding model (optional, knowledge base quality related search)

varied	The default value	Should not change.
EMBEDDING_BASE_URL	空	Production configuration is recommended. Use a built-in 256-dimensional local embedder, available but the quality is not suitable for production; point to any OpenAI format /v1/embeddings Endpoint is.
EMBEDDING_API_KEY	空	Depending on service embedded.
EMBEDDING_MODEL	text-embedding-3-small	Change your embedded service.
EMBEDDING_DIM	1536	** The output dimension must be consistent with the embedding model. ** Qdrant uses independent collection by dimension, which returns a local 256-dimensional embedder.

MinerU Document Analysis (optional)

varied	The default value	Should not change.
MINERU_API_URL	https://mineru.net	Generally unchanged
MINERU_API_KEY	空	Optional: OCR resolution for scanned/pictured PDFs; this type of document can still be uploaded to the knowledge base when it is not configured, but only one line of localized text.

Code sandbox (note status, usually nothing set)

The sandbox service starts with this stack. app By accessing it through a private network, both parties share the same built-in default API key, which is opened for use only when the default limit needs to be covered:

varied	The default value	Explained
SANDBOX_API_KEY	Incorporated shared value	When using the custom API key, app 与 sandbox Read at the same time.
SANDBOX_MEMORY	2g	Memory upper limit for each session container
SANDBOX_CPUS	1	CPU quota for each session container
SANDBOX_MAX_SESSIONS	16	Limit the number of sandbox sessions.
SANDBOX_WORKSPACE_SIZE	512m	every session /workspace The size
SANDBOX_NETWORK	none	The sandbox code. ** Without Networks ** It needs to be changed when it comes to networking. bridge

Sandbox architecture and security boundaries Deployment of Sandbox Please keep in the admin console settings. sandbox_base_url / sandbox_api_key The two fields are empty, so the built-in sandbox only comes into effect.

The next step.

• First operating configuration Create administrators, add channels and models, send the first message
• Reverse Proxy and HTTPS Public network deployment must be read, HTTP for 80 ports plus TLS termination layer
• Cloudflare access Remarks when using Cloudflare
• Core environmental variables Complete reference of all deployment level variables