🐳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

• 64GB+ RAM available

• 50GB+ free disk space

• Docker Hub access token (for pulling private images)

• License token (for running enVector)

Step 1: Verify Docker Environment

# 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

# 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:

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

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

Port Configuration

By default, the es2e service is the only service exposed to your local machine, and it listens on port 50050.

If you need to change this port (for example, if 50050 is already in use), you can configure it in the .env file located at the root of the project.

1. Open the .env file.

2. Find the ES2E_HOST_PORT variable and change its value. For example, to use port 51000:

# .env

# Change this value to expose a different port for the ES2 endpoint service
ES2E_HOST_PORT=51000

License Token (JWT)

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

• If ES2_LICENSE_TOKEN is unset or empty in .env, this default is used.

• To use the default, mount your host token file to that path:

volumes:
  - ./token.jwt:/es2/license/token.jwt

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

1. .env: ES2_LICENSE_TOKEN={value}

2. Runtime: ./start_envector.sh --set ES2_LICENSE_TOKEN={value} or ./start_envector.sh ES2_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 ES2_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): /es2/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 ES2_LICENSE_TOKEN in .env because the default container path matches the mounted file.

Examples

Default path:

volumes:
  - ./token.jwt:/es2/license/token.jwt

# either leave empty or set explicitly
ES2_LICENSE_TOKEN=/es2/license/token.jwt

Custom file name/path:

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

ES2_LICENSE_TOKEN=/custom/path/license.jwt

Generic pattern:

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 file includes default configurations for all services. Verify the configuration:

# 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-es2c 4          # CPU-only: scale es2c=4
./start_envector.sh --gpu --num-es2c 2    # GPU: gpu0 + gpu1

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

# Inline env overrides (higher precedence than .env)
./start_envector.sh ES2E_HOST_PORT=50055 VERSION_TAG=dev

# Stop the stack (use -p if you set a project)
./start_envector.sh --down
# e.g., ./start_envector.sh -p my-es2 --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.

Step 4: Verify Network Configuration

# 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.

# 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.

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

Resource Issues

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

# 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.

# 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.

# 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.