Quick Start¶

Get Vectis Commerce running locally in under 5 minutes.

Prerequisites¶

Docker + Docker Compose v2
Python 3.12+
Node.js 22+

1. Start Infrastructure¶

cd vectis
docker compose up -d

This starts PostgreSQL, Redis, Redpanda, Temporal, Meilisearch, Typesense, MinIO, and their UIs.

2. Install Dependencies¶

make setup

Or manually:

cd backend && pip install -e ".[dev]"
cd ../admin && npm install
cd ../storefront && npm install

3. Initialize the Database¶

make migrate-init

This runs Alembic migrations and seeds the database with a default channel, sample products, exchange rates, and admin user.

4. Start Dev Servers¶

Run each in a separate terminal:

make api              # FastAPI on :8000
make worker           # Temporal worker
make admin-dev        # Admin on :5173
make storefront-dev   # Storefront on :5174

5. Open the Apps¶

App	URL	Credentials
Admin Panel	http://localhost:5173	`admin@vectis.local` / `admin`
Storefront	http://localhost:5174	Guest or create account
GraphQL IDE	http://localhost:8000/graphql	—
Redpanda Console	http://localhost:8080	—
Temporal UI	http://localhost:8088	—
Meilisearch (admin search)	http://localhost:7700	Key: `vectis-dev-key`
Typesense (storefront search)	http://localhost:8108	Key: `vectis-dev-key`
MinIO Console	http://localhost:9001	`minioadmin` / `minioadmin`
Mailpit (dev email)	http://localhost:8025	—

Environment Variables¶

Copy the example env file and adjust as needed:

cp .env.example .env

Key variables:

Variable	Default	Description
`DATABASE_URL`	`postgresql+asyncpg://vectis:vectis@localhost:5432/vectis`	PostgreSQL connection
`REDIS_URL`	`redis://localhost:6379/0`	Redis for sessions and cache
`REDPANDA_BROKER`	`localhost:19092`	Redpanda broker address
`TEMPORAL_HOST`	`localhost:7233`	Temporal server
`SECRET_KEY`	(required)	JWT signing key — generate with `python -c "import secrets; print(secrets.token_urlsafe(64))"`
`MEILISEARCH_URL`	`http://localhost:7700`	Admin search engine (Meilisearch)
`MEILISEARCH_API_KEY`	`vectis-dev-key`	Meilisearch admin key
`TYPESENSE_URL`	`http://localhost:8108`	Storefront search engine (Typesense)
`TYPESENSE_API_KEY`	`vectis-dev-key`	Typesense admin key
`TYPESENSE_SEARCH_ONLY_KEY`	`vectis-search-key`	Typesense search-only key (for scoped key generation)

Docker Compose Services¶

The full docker-compose.yml includes 16 services:

Service	Image	Purpose
`api`	Custom (backend/)	FastAPI application server
`admin`	Custom (admin/)	SvelteKit admin dashboard
`storefront`	Custom (storefront/)	SvelteKit storefront
`postgres`	postgres:16-alpine	Primary database
`redis`	redis:7-alpine	Session store + cache
`redpanda`	redpandadata/redpanda	Event streaming (Kafka-compatible)
`redpanda-console`	redpandadata/console	Redpanda management UI
`temporal`	temporalio/auto-setup	Workflow engine
`temporal-worker`	Custom (backend/)	Temporal activity worker
`temporal-ui`	temporalio/ui	Temporal management UI
`meilisearch`	getmeili/meilisearch	Admin full-text search
`typesense`	typesense/typesense:27.1	Storefront product search
`minio`	minio/minio	S3-compatible object storage
`minio-setup`	minio/mc	One-shot init job that creates MinIO buckets/keys
`mailpit`	axllent/mailpit	Dev SMTP + webmail UI at localhost:8025
`event-consumer`	Custom (backend/)	Redpanda event consumer

Useful Make Commands¶

make help              # List all commands
make up / make down    # Start/stop Docker services
make test              # Run pytest suite
make lint              # Lint with Ruff
make typecheck         # Type check with mypy
make check             # All quality checks