Octop/docker/README.md

Octop Docker Deployment

---

This directory contains the Docker build and deployment assets for Octop.

Files

File	Description
Dockerfile	Multi-stage image definition (build context is the repo root)
../.dockerignore	Build context ignore rules (applies to both Podman and BuildKit)
docker_build.sh	Build image from source (BuildKit cache enabled by default)
docker-compose.yml	One-command local / self-hosted deployment
docker-compose.postgres.yml	PostgreSQL (+ pgvector) for dual-backend dev/tests
postgres/init-vector.sql	Instance-level CREATE EXTENSION vector (initdb.d; not Octop migrations)
docker-entrypoint.sh	Container entrypoint: first-run init + start server

Quick start

Option 1: Compose (recommended)

From the repository root:

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

Open http://localhost:8088. A valid OCTOP_DEFAULT_PASSWORD (≥8 characters with letters and digits) creates the admin on first boot and writes credentials to /data/.octop/credential.txt. If the variable is unset, or the password fails policy (too short, missing letters/digits, or a common password), no admin is created — open the dashboard and complete the setup wizard. The wizard unlock password is in /data/.octop/octop-login.txt (also noted in credential.txt).

Option 2: Build script

bash docker/docker_build.sh
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  octop:latest

Faster downloads (China mirrors)

Pass mirror env vars when building:

PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \
PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \
NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \
APT_MIRROR=mirrors.cloud.tencent.com \
bash docker/docker_build.sh

Environment variables

Variable	Default	Description
HOME	/data	Must be /data so ~/.octop maps to the data volume
OCTOP_PORT	8088	HTTP listen port
OCTOP_DEFAULT_PASSWORD	(unset)	First-run admin password (≥8 chars, letters + digits). Valid → octop init; unset or rejected → web setup wizard
OCTOP_ADMIN_USERNAME	admin	Initial admin username
OCTOP_DATABASE_URL	—	PostgreSQL DSN (or other OCTOP_DATABASE_*; see configuration.md)
OCTOP_DATABASE_DRIVER	—	sqlite | postgresql when overriding defaults via env
OPENAI_API_KEY	—	OpenAI-compatible API key
DASHSCOPE_API_KEY	—	Alibaba DashScope API key

For Compose, put these in docker/.env. Values only reach the container if listed under environment: in docker-compose.yml (Compose interpolates .env; it does not auto-export every key). Alternatively write the same keys into the mounted data dir as ~/.octop/env.

Data persistence

• Compose mounts host ~/.octop → container /data/.octop
• docker run example uses named volume octop-data
• First boot: a valid OCTOP_DEFAULT_PASSWORD runs octop init and writes credential.txt; unset or rejected passwords skip admin creation and write the wizard unlock password to /data/.octop/octop-login.txt. The container does not exit because of a weak default.

Health check

The image probes GET /api/health:

curl http://localhost:8088/api/health

Operations

docker logs -f octop
docker exec -it octop octop --version
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d --build