> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/get-started/installation/docker-compose.md).

# Docker Compose

This step configures your Docker environment for running `enVector` services.

### Overview

We'll set up Docker Compose to run all `enVector` services locally. This approach provides:

* **Simplicity**: Single command to start all services
* **Isolation**: Each service runs in its own container
* **Consistency**: Same environment across different machines
* **Easy Management**: Simple start/stop/restart commands

### Prerequisites

* Docker Engine running
* Docker Compose v2.0+ installed
* 32GB+ RAM available
* 50GB+ free disk space
* Docker Hub access token (for pulling private images)
* License token (for running `enVector`)

## Step 1: Verify Docker Environment

```bash
# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Verify Docker daemon is running
docker info

# Test with a simple container
docker run hello-world
```

## Step 2: Get Compose Assets

Clone the envector deployment repository and work from its docker-compose directory. Repository: [envector-deployment](https://github.com/CryptoLabInc/envector-deployment)

```bash
# Clone the deployment repo and move to its docker-compose directory
git clone https://github.com/CryptoLabInc/envector-deployment.git
cd ./envector-deployment/docker-compose

# Make the helper script executable
chmod +x ./start_envector.sh

# Verify files are in place
ls -la
```

#### Docker Hub Login (automatic)

`./start_envector.sh` performs preflight checks. If access to `cryptolabinc/*` images is required, it will prompt for a Docker Hub PAT and run a non‑interactive login:

```bash
cat patfile | docker login -u cltrial --password-stdin
```

You can also login manually ahead of time if you prefer.

#### Port Configuration

By default, the `envector-endpoint` service is the only service exposed to your local machine. It listens on:

* `50050` for the gRPC API (`ENVECTOR_ENDPOINT_HOST_PORT`)
* `18080` for the HTTP health/admin endpoints (`ENVECTOR_HTTP_HEALTH_HOST_PORT`)

If you need to change these ports (for example, if `50050` is already in use), configure them in the `.env` file located in the `docker-compose` directory.

1. Open the `.env` file.
2. Find the relevant variable and change its value. For example, to use port `50055` for the gRPC endpoint:

```
# .env

# Change this value to expose a different port for the endpoint service
ENVECTOR_ENDPOINT_HOST_PORT=50055

# Change this value to expose a different port for the HTTP health/admin endpoints
ENVECTOR_HTTP_HEALTH_HOST_PORT=18081
```

### License Token (JWT)

By default, enVector reads the license token at `/envector/license/token.jwt` inside the container.

* If `ENVECTOR_LICENSE_TOKEN` is unset or empty in `.env`, this default is used.
* To use the default, mount your host token file to that path:

```yml
volumes:
  - ./token.jwt:/envector/license/token.jwt
```

You can provide the JWT in either of the following ways:

1. `.env`: `ENVECTOR_LICENSE_TOKEN={value}`
2. Runtime: `./start_envector.sh --set ENVECTOR_LICENSE_TOKEN={value}` or `./start_envector.sh ENVECTOR_LICENSE_TOKEN={value}`

Where `{value}` is either:

* a host file path (that you will mount), or
* the raw JWT string.

If you use a file path:

* Mount the host file into the container.
* Set `ENVECTOR_LICENSE_TOKEN` to the in-container path you mounted to (or leave it empty to use the default).

Defaults

* Host path (recommended): `./token.jwt` in your working directory
* Container path (default): `/envector/license/token.jwt`

Note

* If `token.jwt` is missing, `./start_envector.sh` will prompt for a path and copy the file into this directory automatically.
* In most cases you don’t need to set `ENVECTOR_LICENSE_TOKEN` in `.env` because the default container path matches the mounted file.

Examples

Default path:

```yml
volumes:
  - ./token.jwt:/envector/license/token.jwt
```

```bash
# either leave empty or set explicitly
ENVECTOR_LICENSE_TOKEN=/envector/license/token.jwt
```

Custom file name/path:

```yml
volumes:
  - ./secrets/my-license.jwt:/custom/path/license.jwt
```

```bash
ENVECTOR_LICENSE_TOKEN=/custom/path/license.jwt
```

Generic pattern:

```yml
volumes:
  - ./{path_to_jwt_dir}/token.jwt:/{mount_path_in_container}/token.jwt
```

## Step 3: Verify Docker Compose Configuration

The `docker-compose.envector.yml` and `docker-compose.infra.yml` files include default configurations for all services. Verify the configuration:

```bash
# Baseline: application + infrastructure
./start_envector.sh

# Print merged compose config (no containers started)
./start_envector.sh --config

# GPU override (requires NVIDIA Container Toolkit)
./start_envector.sh --gpu

# Scale workers
./start_envector.sh --num-compute 4          # CPU-only: scale envector-compute=4
./start_envector.sh --gpu --num-compute 2    # GPU: gpu0 + gpu1

# Project/env/log options
./start_envector.sh -p my-envector --env-file ./.env --log-file ./docker-logs.log

# Inline env overrides (higher precedence than .env)
./start_envector.sh ENVECTOR_ENDPOINT_HOST_PORT=50055 VERSION_TAG=dev
./start_envector.sh ENVECTOR_HTTP_HEALTH_HOST_PORT=18081
./start_envector.sh ENVECTOR_ADMIN_API_ENABLED=true

# Stop the stack (use -p if you set a project)
./start_envector.sh --down
# e.g., ./start_envector.sh -p my-envector --down
# Remove volumes as well when stopping
./start_envector.sh --down --down-volumes

# Validate docker-compose-***.yml (no containers started)
docker compose -f docker-compose.envector.yml -f docker-compose.infra.yml config

# Check service definitions (after a run)
docker compose -f docker-compose.envector.yml -f docker-compose.infra.yml ps

# Note: `docker compose up` automatically pulls required images
# based on the tags referenced in the compose files.
```

### HTTP health and admin endpoints

Once the stack is up, you can probe the endpoint service directly over HTTP:

```bash
# Health
curl http://localhost:${ENVECTOR_HTTP_HEALTH_HOST_PORT:-18080}/health
curl http://localhost:${ENVECTOR_HTTP_HEALTH_HOST_PORT:-18080}/health/ready

# Admin API (requires ENVECTOR_ADMIN_API_ENABLED=true)
curl http://localhost:${ENVECTOR_HTTP_HEALTH_HOST_PORT:-18080}/admin/services
curl http://localhost:${ENVECTOR_HTTP_HEALTH_HOST_PORT:-18080}/admin/indexes
curl http://localhost:${ENVECTOR_HTTP_HEALTH_HOST_PORT:-18080}/admin/keys

# Swagger UI
open http://localhost:${ENVECTOR_HTTP_HEALTH_HOST_PORT:-18080}/swagger/
```

## Step 4: Verify Network Configuration

```bash
# Check Docker networks
docker network ls

# Test network connectivity
docker run --rm alpine ping -c 3 google.com
```

## Troubleshooting

#### Docker Daemon Issues

If you encounter errors related to the Docker daemon not being active, you can start it with the following commands.

```bash
# On Ubuntu/Debian systems
sudo systemctl start docker
sudo systemctl enable docker
```

#### Permission denied

This error typically means your user account is not part of the `docker` group. Add your user to the group and then apply the changes.

```bash
# Add the current user to the docker group
sudo usermod -aG docker $USER
```

#### Resource Issues

The services require a significant amount of memory (32GB+ recommended). Use these commands to check your system's available memory.

```bash
# Check available memory
free -h

# Review your Docker daemon's resource configurations
sudo cat /etc/docker/daemon.json
```

#### Disk space issues

Ensure you have at least 50GB of free disk space. You can check your disk usage and clean up unused Docker assets (images, containers, volumes) to free up space.

```bash
# Check available disk space
df -h

# Prune the Docker system to remove unused data
docker system prune -a
```

#### Network Issues

Cannot pull images from Docker Hub

If Docker is unable to pull images, it may be due to a network or DNS issue.

```bash
# 1. Test general internet connectivity
ping 8.8.8.8

# 2. Test connectivity specifically to Docker Hub
docker pull hello-world

# 3. Check if DNS resolution for Docker Hub is working
nslookup docker.io
```

***

### Important Notes

* Resource Monitoring: Actively monitor Docker's CPU, memory, and disk usage to prevent performance bottlenecks.
* Network Access: Ensure your firewall or network policies allow containers to communicate with each other, especially if you are using a custom Docker network.
* Data Persistence: The setup uses Docker volumes to persist critical data. Be mindful of these volumes when managing your containers.
* Cleanup: When you are finished, use the command `docker compose down` to stop and remove all running containers, networks, and volumes associated with the services.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.4.x/get-started/installation/docker-compose.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.