Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
204 lines (144 loc) · 5.91 KB

GETTING_STARTED.md

File metadata and controls

204 lines (144 loc) · 5.91 KB
Raw

Getting Started

Set up the Prebid Sales Agent for local development.

Prerequisites

Tool Version Install
Python 3.12+ python.org
Docker + Compose Latest docker.com
Git Any git-scm.com
uv Latest curl -LsSf https://astral.sh/uv/install.sh | sh
ast-grep Latest brew install ast-grep (macOS) or ast-grep.github.io

Note: ast-grep is a Rust CLI tool used by the ast-grep-bdd-guards pre-commit hook for BDD step structural pattern detection. It cannot be installed via uv — it requires a separate system install. Without it, commits that touch tests/bdd/steps/ will be blocked locally.

One-Command Setup

git clone https://github.com/prebid/salesagent.git
cd salesagent
make setup

make setup runs scripts/setup-dev.py, which handles everything:

  1. Verifies prerequisites (Python, Docker, uv, git)
  2. Installs Python dependencies (uv sync)
  3. Creates .env from .env.template (preserves existing values)
  4. Installs pre-commit hooks
  5. Checks for tox (optional, used by the test runner)
  6. Starts Docker services (docker compose up -d)
  7. Waits for database migrations to complete
  8. Verifies health check at http://localhost:8000/health

When complete, services are running at http://localhost:8000:

Service URL
Admin UI http://localhost:8000/admin/
MCP Server http://localhost:8000/mcp/
A2A Server http://localhost:8000/a2a
Health Check http://localhost:8000/health

Test login: Click "Log in to Dashboard" on the login page (password: test123).

Manual Setup

If you prefer to run each step yourself:

# 1. Clone and enter the repository
git clone https://github.com/prebid/salesagent.git
cd salesagent

# 2. Install Python dependencies
uv sync

# 3. Create .env (optional — defaults work for development)
cp .env.template .env

# 4. Install pre-commit hooks
uvx pre-commit install

# 5. Start Docker services
docker compose up -d

# 6. Verify health
curl http://localhost:8000/health

Migrations run automatically on startup via the db-init container. Docker Compose builds from local source, so code changes are reflected immediately.

Testing

Quick quality check (before every commit)

make quality

Runs: formatting check, linting, type checking, and unit tests.

Full test suite (before merge)

Install tox first (one-time):

uv tool install tox --with tox-uv

Then run all five test suites (unit, integration, integration_v2, e2e, ui) in parallel via Docker:

./run_all_tests.sh

This starts Docker, runs tox, tears down Docker, and saves JSON reports to test-results/. See Testing Patterns for the full reference.

Targeted runs

tox -e unit                            # Unit tests only (no Docker)
tox -e integration -- -k test_name     # Specific integration test
./run_all_tests.sh quick               # No Docker: unit + integration + integration_v2
./run_all_tests.sh ci tests/integration/test_file.py -k test_name

Common Operations

View logs

docker compose logs -f          # All services
docker compose logs -f adcp-server  # Just the app server

Stop and restart

docker compose down             # Stop services
docker compose up -d            # Start again
docker compose down -v          # Stop and reset database

Rebuild after dependency changes

docker compose build && docker compose up -d

Run database migrations manually

# Locally
uv run python scripts/ops/migrate.py

# Inside Docker
docker compose exec adcp-server python scripts/ops/migrate.py

# Create a new migration
uv run alembic revision -m "description"

Test the MCP interface

uvx adcp http://localhost:8000/mcp/ --auth test-token list_tools
uvx adcp http://localhost:8000/mcp/ --auth test-token get_products '{"brief":"video"}'

Type checking

uv run mypy src/core/your_file.py --config-file=mypy.ini

Fix formatting and lint errors

make lint-fix

Conductor Workspaces

Conductor is a Mac app that runs multiple development workspaces in parallel, each in its own git worktree with an isolated Docker environment. To set up a workspace, run the setup script from inside it:

./scripts/setup/setup_conductor_workspace.sh

The script copies .env from the Conductor root directory (create it there first — see Environment Configuration), assigns the workspace a unique port, and starts the Docker stack. When you archive a workspace, release its Docker resources:

./scripts/setup/cleanup_conductor_workspace.sh

Environment Configuration

The .env file is created from .env.template during setup. Key variables:

Variable Default Purpose
ADCP_AUTH_TEST_MODE true Enables test login (disable for production)
CREATE_DEMO_TENANT false Creates sample data on first startup
ENVIRONMENT development development = strict validation, production = lenient
CONDUCTOR_PORT 8000 Nginx proxy port

For OAuth, GAM integration, and other production settings, see the comments in .env.template or Environment Variables.

Next Steps