Quick Start¶

Get Vectis Commerce running locally in under 5 minutes.

Prerequisites¶

• Docker + Docker Compose v2
• Python 3.12+
• Node.js 22+
• Access to both the core (vectis-commerce) and enterprise-extensions repos

1. Clone Both Repos¶

All extensions live in the separate enterprise-extensions repo. Clone it as a sibling of the core repo, in the same parent directory — docker-compose.yml bind-mounts ../enterprise-extensions read-only into the API container and dev-links it via VECTIS_DEV_EXTENSIONS:

git clone git@github.com:vectiscommerce/vectis-commerce.git vectis
git clone git@github.com:vectiscommerce/enterprise-extensions.git enterprise-extensions

Without the sibling checkout, starting the containers fails (the bind mount is missing) and no extensions are discovered.

2. Start Infrastructure¶

cd vectis
docker compose up -d

This starts PostgreSQL, Valkey, Redpanda, Temporal, Meilisearch, Typesense, RustFS, and their UIs.

3. Install Dependencies¶

make setup

Or manually:

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

4. 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. Then create the Temporal schedules (one-time, after the services are up):

make schedules

5. 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

6. Open the Apps¶

Most tool UIs are not published on host localhost ports — the containers only expose: their ports internally and are reached through the shared Caddy dev-proxy at *.vectis.eto (see the dev-proxy reference). Add the *.vectis.eto hosts to /etc/hosts (or run the proxy's setup) before opening these.

The following services are host-mapped and reachable directly on localhost (data/protocol endpoints, not web UIs):

Environment Variables¶

Copy the example env file and adjust as needed:

cp .env.example .env

Key variables:

Docker Compose Services¶

The full docker-compose.yml includes 21 app services (plus a one-shot rustfs-setup init job). The api service mounts the sibling ../enterprise-extensions checkout read-only and discovers it via VECTIS_DEV_EXTENSIONS:

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 (single source of truth)

make check is the gate. It runs Ruff, mypy, the resolver-duplicate AST guard, the zero-extension-imports AST guard, the extension→core import ratchet, the extension-migration-ownership guard, the model-drift guard, the extensions.lock gate, the schema-drift guard, the extension-UI sync gate, and the ~2,260-test pytest suite. Run it from the repo root on the host — each sub-check docker execs into the API container itself. CI is currently disabled in favour of this local gate; push to main once make check passes:

make check

Prometheus + Grafana (Optional)¶

The monitoring services come up with the default docker-compose.yml. Their UIs are proxy-only (see the app table above):