> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Octop Docker Setup: Standalone Docker, Compose, and Configuration Reference

Octop provides a pre-built Docker image that wraps the entire platform — web UI, CLI, IM channels, and agent runtime — into a single container.

`:latest` and `:<version>` are the lite image. Virtual desktop, OCR, and local embedding are on `:<version>-full` and `:full`. A local image build is full unless you pass `--build-arg OCTOP_IMAGE_VARIANT=lite`.

Choose the setup method that best suits your needs:

- **Standalone Docker (`docker run`)**: A fast, single-command startup without cloning the repository. Supports both the Nanjing University China mirror and the official GitHub Packages registry.
- **Docker Compose (`docker compose`)**: Recommended for production and multi-user environments with persistent configuration management. Octop provides both a build-free China mirror configuration (`docker-compose.cn.yml`) and a standard source-build configuration (`docker-compose.yml`).

***

## Method 1: Standalone Docker (`docker run`)

If you want a lightweight single-command startup without managing complex service dependencies, run `docker run` directly:


**China Mirror (Recommended for China)**

Uses the Nanjing University mirror proxy for GHCR for faster, reliable downloads within China:
```bash
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  ghcr.nju.edu.cn/tencentcloud/octop:latest
```


**GitHub Source (Official)**

Pulls directly from GitHub Packages (GHCR), suitable for overseas servers or environments with direct GitHub access:
```bash
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  ghcr.io/tencentcloud/octop:latest
```


### Parameter Reference

| Parameter                         | Description                                                                                                                                                                                                |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name octop`                    | Names the container `octop`.                                                                                                                                                                               |
| `-p 8088:8088`                    | Maps container port 8088 to host port 8088. Change the host port if needed (e.g. `-p 9090:8088`).                                                                                                          |
| `-v octop-data:/data/.octop`      | Uses the Docker named volume `octop-data` to persist databases, keys, and configurations across container restarts and updates. You can also bind mount a host directory, e.g. `-v ~/.octop:/data/.octop`. |
| `-e HOME=/data`                   | **Required**. Sets the container user home to `/data` so `~/.octop` resolves to the mounted volume path `/data/.octop`.                                                                                    |
| `-e OCTOP_DEFAULT_PASSWORD="..."` | _(Optional)_ Pre-configures the initial admin password (must be ≥ 8 characters and include both letters and digits). If unset, the container launches the web setup wizard on first boot.                  |

***

## Method 2: Docker Compose Setup

For production deployments or setups requiring managed environment variables, use Docker Compose. Octop provides two official Compose configuration files:


**China Mirror Configuration (docker-compose.cn.yml)**

Source link: [docker-compose.cn.yml](https://github.com/TencentCloud/Octop/blob/main/docker/docker-compose.cn.yml)
**Highlights**:
- **No local build required**: Uses the pre-built image from the Nanjing University GHCR mirror `ghcr.nju.edu.cn/tencentcloud/octop:latest`.
- **No need to clone the repository**: You can download this single YAML file and launch it immediately.
- Optimized for servers in mainland China to eliminate GHCR network latency and failures.
**Quick Start**:
```bash
# Step 1: Download the Compose file directly (no git clone required)
curl -fsSL https://raw.githubusercontent.com/TencentCloud/Octop/main/docker/docker-compose.cn.yml -o docker-compose.cn.yml

# Step 2: Start the container
docker compose -f docker-compose.cn.yml up -d
```
If you have already cloned the Octop repository, run it directly from the repository root:
```bash
docker compose -f docker/docker-compose.cn.yml up -d
```


**Standard / Source Build Configuration (docker-compose.yml)**

Source link: [docker-compose.yml](https://github.com/TencentCloud/Octop/blob/main/docker/docker-compose.yml)
**Highlights**:
- Includes build instructions (`docker/Dockerfile`) for a multi-stage build (Node.js frontend + Python 3.12 runtime) tagged as `octop:latest`.
- Ideal for overseas networks or developers making code modifications and testing custom local builds.
**Quick Start** (run from the root of the cloned repository):
```bash
# Start the container (builds from source on first run)
docker compose -f docker/docker-compose.yml up -d

# Rebuild and restart after source code changes
docker compose -f docker/docker-compose.yml up -d --build
```


***

## Docker Compose Configuration Breakdown

Both `docker-compose.cn.yml` and `docker-compose.yml` share identical service settings and environment variables:

### 1. Service and System Limits (`services.octop`)

```yaml
services:
  octop:
    container_name: octop
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
```

- **`restart: unless-stopped`**: Automatically restarts the container if it crashes or after system reboots.
- **`ulimits.nofile`**: Raises the file descriptor ceiling to 65535, preventing "Too many open files" errors under concurrent WebSocket connections, multi-agent operations, and frequent file I/O.

### 2. Ports and Volume Persistence

```yaml
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
```

- **`OCTOP_PORT`**: Defaults to port `8088`. You can override it with an environment variable (e.g. `OCTOP_PORT=9090`).
- **`OCTOP_DATA`**: Binds the host user's `~/.octop` directory to `/data/.octop` inside the container. Override it via `OCTOP_DATA` to customize the host storage path (e.g. `OCTOP_DATA=/var/lib/octop`).

### 3. Environment Variables and `.env`

Compose files use `${VAR:-default}` for parameter interpolation. Place a `.env` file in the `docker/` directory (modeled after `.env.example`):

```bash
cp .env.example docker/.env
# Edit docker/.env with your settings
```


> **NOTE**
> 
> `docker/.env` is only used for Compose variable interpolation. Only variables declared under `environment:` in the Compose file will enter the container. Alternatively, write variables directly to `~/.octop/env` in the mounted host directory.
> 


Supported Compose environment variables include:

| Variable                   | Default   | Purpose and Description                                                                                          |
| -------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `HOME`                     | `/data`   | **Must be `/data`** so `~/.octop` resolves to the mounted volume path                                            |
| `OCTOP_BIND_HOST`          | `0.0.0.0` | Listen interface inside the container                                                                            |
| `OCTOP_PORT`               | `8088`    | HTTP listen port                                                                                                 |
| `OCTOP_LOG_LEVEL`          | `info`    | Logging verbosity (`debug`, `info`, `warning`, `error`)                                                          |
| `OCTOP_ADMIN_USERNAME`     | `admin`   | First-run admin username                                                                                         |
| `OCTOP_ADMIN_DISPLAY_NAME` | `Admin`   | First-run admin display name                                                                                     |
| `OCTOP_DEFAULT_PASSWORD`   | _(empty)_ | Pre-configured admin password (must be ≥ 8 chars with letters and digits). If unset, the web setup wizard starts |
| `OCTOP_DATABASE_URL`       | _(empty)_ | External database connection string (e.g. PostgreSQL)                                                            |
| `OCTOP_DATABASE_DRIVER`    | _(empty)_ | Database driver name, e.g. `postgresql`                                                                          |
| `OPENAI_API_KEY`           | _(empty)_ | OpenAI-compatible API key for agent runtime                                                                      |
| `DASHSCOPE_API_KEY`        | _(empty)_ | Alibaba DashScope (Qwen) API key                                                                                 |
| `LANGFUSE_TRACING_ENABLED` | `true`    | Enables Langfuse telemetry and trace capture                                                                     |
| `LANGFUSE_PUBLIC_KEY`      | _(empty)_ | Langfuse public key                                                                                              |
| `LANGFUSE_SECRET_KEY`      | _(empty)_ | Langfuse secret key                                                                                              |
| `LANGFUSE_BASE_URL`        | _(empty)_ | Self-hosted or cloud Langfuse endpoint URL                                                                       |

***

## First-Run Sign In and Setup Wizard

Once the container starts, open your browser and navigate to:

```text
http://localhost:8088
```

The container entrypoint processes initialization based on `OCTOP_DEFAULT_PASSWORD`:


### Scenario A: Valid password pre-configured

If you provided a valid `OCTOP_DEFAULT_PASSWORD` in `docker run -e` or `docker/.env` (≥ 8 characters, letters and digits, non-trivial):
- The container automatically runs `octop init` and creates the admin user.
- Login credentials are saved to `credential.txt` in the volume.
- Sign in directly with the username (default `admin`) and your password.

### Scenario B: Password unset or weak (Setup Wizard)

If `OCTOP_DEFAULT_PASSWORD` is omitted or does not meet the policy:
- The container does **not** loop or fail; it initiates the **Web Setup Wizard**.
- A single-use wizard unlocking password is written to `octop-login.txt` in the data volume (and noted in `credential.txt`).
- Open `http://localhost:8088` in your browser, enter the wizard password, and configure your admin account.

### Viewing Credentials and Wizard Password

```bash
# Docker Compose (host bind mount ~/.octop)
cat ~/.octop/octop-login.txt       # Setup wizard password (if password was unset)
cat ~/.octop/credential.txt        # Credential summary

# Standalone Docker (named volume octop-data)
docker exec octop cat /data/.octop/octop-login.txt
docker exec octop cat /data/.octop/credential.txt
```

### Changing the Admin Password

After signing in, click **Change password** in the avatar menu. You can also change the password anytime via CLI on the host:

```bash
docker exec -it octop octop user passwd <username> --password <new-password>
```


> **NOTE**
> 
> Changing the password in the web UI will not rewrite `credential.txt`; the password set in the UI always takes precedence. If you forget your password, see [Reset password](/en/guide/guides/reset-password.md).
> 


***

## Useful Operations

To pull a new image and keep the data volume, see [Upgrade](/en/guide/guides/upgrade.md).

```bash
# Stream container logs
docker logs -f octop

# Run a CLI command inside the container (check version)
docker exec -it octop octop --version

# Stop and remove the container (standalone Docker)
docker stop octop && docker rm octop

# Stop the Compose service
docker compose -f docker-compose.cn.yml down
# or
docker compose -f docker/docker-compose.yml down

# Check container health status
curl http://localhost:8088/api/health
```

## Serve under a subpath

The default image expects the site at the domain root. To publish it at `https://example.com/octop/`, rebuild the frontend with `VITE_BASE_PATH=/octop/` and strip that prefix in the reverse proxy (`proxy_pass` with a trailing slash).


[**Bare-metal Quickstart**](/en/guide/quickstart.md)

Install Octop directly on macOS, Linux, or Windows without Docker using the one-line installer.

[**Configuration Reference**](/en/guide/configuration/config-file.md)

Explore all `config.json` keys and environment variable overrides for fine-grained control.

[**Use on Tencent Cloud**](/en/guide/use-in-tencent-cloud.md)

Launch a Lighthouse or CVM instance with the official Octop image.

[**FnOS NAS**](/en/guide/fnos.md)

Install Docker or native `.fpk` packages on Feiniu NAS.
