Setup

This skill sets up and launches the Retail Agentic Commerce project. It supports two deployment modes.

Step 1: Ask the User (MANDATORY)

You MUST ask the user which deployment mode they want before proceeding. Do NOT skip this step. Do NOT assume a mode.

Present these two options with Docker as the default:

1. Docker (Recommended, default) — runs everything in containers via Docker Compose. No local Python/Node setup needed.
2. Local Development — runs infrastructure in Docker, but backend services, agents, and UIs run directly on the host for faster iteration.

If the user says "setup" or "install" without specifying a mode, ask them. Default to Docker only if the user explicitly says "just do it" or "default".

Shared Prerequisites (Both Modes)

Environment Configuration

1. Create .env from template (if it doesn't exist)

bash
1cp env.example .env

If .env already exists, do NOT overwrite it — check its contents instead.

2. Validate NVIDIA_API_KEY

Read the .env file and check that NVIDIA_API_KEY is set to a real value:

• Valid: NVIDIA_API_KEY=nvapi-... (a real key starting with nvapi-)
• Invalid: NVIDIA_API_KEY=nvapi-xxx, NVIDIA_API_KEY=, or missing entirely

If the key is missing or is the placeholder nvapi-xxx:

1. Stop and tell the user:

   Your NVIDIA_API_KEY is not configured. Get a free API key at https://build.nvidia.com/settings/api-keys and set it in your .env file.

2. Do NOT proceed until the user provides a valid key.

3. Verify Public NIM Endpoint Configuration

Confirm these values are set in .env (they are the defaults from env.example):

env
1NIM_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
2NIM_EMBED_BASE_URL=https://integrate.api.nvidia.com/v1

If they point to a different host (e.g., a local NIM or internal server), inform the user and ask if they want to keep them or reset to public endpoints.

Mode A: Docker Deployment

Prerequisites

bash
1docker --version        # Required: Docker 24+
2docker compose version  # Required: Docker Compose v2+
3docker info > /dev/null 2>&1  # Daemon must be running

If any check fails, stop and inform the user what to install or start.

Launch Services

bash
1docker network create acp-infra-network || true
2docker compose -f docker-compose.infra.yml -f docker-compose.yml up --build -d

This starts:

• Infrastructure: Milvus (vector DB), MinIO (object storage), etcd, Phoenix (tracing)
• Backend: Merchant API (port 8000), PSP service (port 8001), Apps SDK MCP (port 2091)
• Agents: Promotion (8002), Post-Purchase (8003), Recommendation (8004), Search (8005)
• UI: Next.js demo frontend
• Nginx: Reverse proxy exposing everything on port 80

Wait for Services

bash
1docker compose -f docker-compose.infra.yml -f docker-compose.yml ps

Milvus and agents may take 30–60 seconds to initialize.

Health Verification

bash
1# Core services
2curl -s http://localhost/api/health
3curl -s http://localhost/psp/health
4curl -s http://localhost/apps-sdk/health
5
6# NAT agents (internal-only, check from merchant container)
7docker compose -f docker-compose.infra.yml -f docker-compose.yml exec merchant \
8  python -c "
9import urllib.request as u
10for name, url in [
11    ('promotion', 'http://promotion-agent:8002/health'),
12    ('post-purchase', 'http://post-purchase-agent:8003/health'),
13    ('recommendation', 'http://recommendation-agent:8004/health'),
14    ('search', 'http://search-agent:8005/health'),
15]:
16    try:
17        status = u.urlopen(url, timeout=5).status
18        print(f'{name}: {status}')
19    except Exception as e:
20        print(f'{name}: FAILED ({e})')
21"

Post-Setup Summary

Setup complete (Docker). All services are running.

  Demo UI:        http://localhost
  API Health:     http://localhost/api/health
  PSP Health:     http://localhost/psp/health
  Apps SDK Health: http://localhost/apps-sdk/health
  API OpenAPI:    http://localhost/api/openapi.json
  PSP OpenAPI:    http://localhost/psp/openapi.json
  Apps SDK OpenAPI: http://localhost/apps-sdk/openapi.json
  Phoenix Traces: http://localhost:6006
  MinIO Console:  http://localhost:9001

Troubleshooting

• Port conflicts: lsof -i :80 — stop the conflicting service or change the nginx port in docker-compose.yml
• Crash loops: docker compose -f docker-compose.infra.yml -f docker-compose.yml logs -f <service-name>
• Full reset: docker compose -f docker-compose.infra.yml -f docker-compose.yml down -v then re-run up --build -d

Mode B: Local Development

Quick Start

Run the automated setup script from the project root:

bash
1./install.sh

To stop all services:

bash
1./stop.sh

What the Script Does

1. Validates prerequisites — Python 3.12+, uv, Node.js 18+, pnpm
2. Configures environment — Creates .env from env.example if missing, validates NVIDIA_API_KEY
3. Installs dependencies — Root venv (uv sync), agents venv (uv pip install), UI (pnpm install), Apps SDK widget
4. Starts 8 services in background with PID tracking
5. Runs health checks and prints a status table

Services Started

Post-Setup Summary

  Demo UI:         http://localhost:3000
  Merchant API:    http://localhost:8000/docs
  PSP:             http://localhost:8001/docs
  Apps SDK MCP:    http://localhost:2091/docs
  Phoenix Traces:  http://localhost:6006  (requires Docker infra)
  MinIO Console:   http://localhost:9001  (requires Docker infra)

Troubleshooting

• View logs: tail -f logs/<service>.log
• Port conflicts: lsof -i :<port> — stop the conflicting process or change the port
• Re-run setup: ./install.sh stops existing services first (idempotent)
• Docker infrastructure (Milvus, Phoenix, MinIO): Optional. Start with docker compose -f docker-compose.infra.yml up -d

Execution Order (Strict)

Follow these steps in order — do not skip:

1. Ask the user: Docker or Local deployment
2. Validate .env exists and NVIDIA_API_KEY is a real key
3. Verify NIM endpoint URLs
4. Check prerequisites for the chosen mode
5. Start infrastructure
6. Start services (all at once for Docker, per-terminal for local)
7. Run health checks
8. Report success with URLs