Run With Docker Compose#

Use this path to run the Semantic Search Agent inside a container. The REST API is exposed on host port 8080 and Prometheus metrics on port 9090.

Before You Start#

  • Copy and configure the environment file:

    cp .env.example .env

  • Edit .env to set DEFAULT_MATCHING_STRATEGY and the appropriate VLM backend variables. For exact-only matching, no VLM variables are needed.

  • Review config/inventory.json and config/orders.json and update them to match your data. These files are mounted read-only into the container.

  • An optional redis service is included in the Compose file. It is started alongside the main service but is only used when CACHE_BACKEND=redis.

Start the Service#

From the semantic-search-agent/ directory:

# Build the Docker image
cd docker
docker compose build

# Start containers in detached mode
docker compose up -d

Or using the Makefile from the project root:

make docker-build
make docker-up

Check Status#

# Verify process status
docker compose -f docker/docker-compose.yml ps

# Hit health check
curl http://localhost:8080/api/v1/health

Follow Logs#

To tail the logs of the running service:

make docker-logs

Or directly with Docker Compose:

docker compose -f docker/docker-compose.yml logs -f semantic-service

Restart after configuration updates#

If you only change config/inventory.json or config/orders.json, restart the container:

docker compose -f docker/docker-compose.yml restart semantic-service

If you modify environment variables in .env, recreate the containers:

make docker-down
make docker-up

Stop the Service#

make docker-down

Prometheus Metrics#

When the service is running, Prometheus metrics are available at:

curl http://localhost:9090/metrics

API Documentation#

The service exposes interactive Swagger UI documentation while running:

http://localhost:8080/docs

API Use Cases and Examples#

For API use cases, request examples, and endpoint details, see the API Reference.