Setup

This skill sets up and launches the Retail-Agentic-Commerce project. It supports Docker deployment and local development.

Ask First

Ask which deployment mode the user wants before proceeding unless they already specified one:

1. Docker, recommended default: runs everything in containers via Docker Compose.
2. Local development: runs infrastructure in Docker, but backend services, agents, and UIs run directly on the host.

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

Shared Prerequisites

Create .env from the template if it does not exist:

cp env.example .env

Do not overwrite an existing .env.

Validate that NVIDIA_API_KEY is set to a real key:

• Valid: starts with nvapi- and is not the placeholder.
• Invalid: missing, empty, or nvapi-xxx.

If the key is missing or placeholder, stop and tell the user to create a key at https://build.nvidia.com/settings/api-keys and set it in .env.

Confirm these public NIM endpoint defaults unless the user intentionally configured another host:

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

Docker Deployment

Check prerequisites:

docker --version
docker compose version
docker info

Launch services:

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

Check service status:

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

Verify core health endpoints:

curl -s http://localhost/api/health
curl -s http://localhost/psp/health
curl -s http://localhost/apps-sdk/health

Verify NAT agents from the merchant container because Docker agents are internal-only:

docker compose -f docker-compose.infra.yml -f docker-compose.yml exec merchant \
  python -c "
import urllib.request as u
for name, url in [
    ('promotion', 'http://promotion-agent:8002/health'),
    ('post-purchase', 'http://post-purchase-agent:8003/health'),
    ('recommendation', 'http://recommendation-agent:8004/health'),
    ('search', 'http://search-agent:8005/health'),
]:
    try:
        status = u.urlopen(url, timeout=5).status
        print(f'{name}: {status}')
    except Exception as e:
        print(f'{name}: FAILED ({e})')
"

Report these URLs when Docker setup succeeds:

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

Local Development

Run the automated setup script from the repo root:

./install.sh

Stop services with:

./stop.sh

The script validates prerequisites, creates .env from env.example if missing, validates NVIDIA_API_KEY, installs dependencies, starts services, and runs health checks.

Expected local URLs:

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
MinIO Console: http://localhost:9001

Troubleshooting

• View local logs with tail -f logs/<service>.log.
• Check Docker logs with docker compose -f docker-compose.infra.yml -f docker-compose.yml logs -f <service-name>.
• Inspect port conflicts with lsof -i :<port>.
• For Docker reset, run docker compose -f docker-compose.infra.yml -f docker-compose.yml down -v, then launch again.

Completion Criteria

Report the chosen mode, commands run, health check results, URLs, and any services that failed to start.