Guide / Local development

Run a Rust ecommerce prototype locally.

See the storefront and merchant workspace first. Add AI inference and agent clients as separate steps.

1. Check the prerequisites

Rust stable 1.96+ with cargo on your PATH
Node.js 22 or newer and npm
A running Docker daemon with Docker Compose
Python 3; free ports 8787, 15487 and 16333

Ollama and cloud API keys are optional for the initial commerce tour.

2. Start the commerce app

git clone https://github.com/sthamann/vendune.git
cd vendune
./scripts/dev.sh

The first start pulls PostgreSQL/Qdrant images and builds the frontend and Rust application. It may take several minutes. No model is downloaded. Keep the terminal open while the app runs, then open http://127.0.0.1:8787/.

3. Explore a synthetic shop

Open Vendune Studio at /#merchant. On the Studio login page, select Create shop to create a personal owner account and a synthetic shop. Try product variants, quantity prices, cart and simulated checkout.

The generated private .env contains an instance bootstrap credential. Ordinary merchants should use personal accounts. Do not distribute the global merchant token.

The local tour uses simulated/manual payments. Explicitly configured PayPal Sandbox/Live is separate; actual PSP transactions remain unverified. This prototype is for local exploration.

Create the connected playground

After creating your personal merchant account, run:

python3 scripts/playground.py --email your-personal-merchant@example.test

Enter that account's password privately. The script creates a separate shop with a coupon, sales channel, engraving app and active branching invoice flow. It prints the shop links; repeating setup preserves your edits. No model calls or orders are made by setup. Follow the hands-on tour.

4. Add local AI when you need it

Install and start Ollama, then explicitly download the documented models:

ollama pull qwen3.6:35b
ollama pull qwen3-embedding:0.6b

The default inference artifact is about 24 GB; runtime and context require more memory. A compatible installed model can be configured in OLLAMA_MODEL in the private .env. Smaller models are not advertised as verified alternatives.

Restart after changing .env. In Studio Settings, choose Local. Use Refresh shop knowledge when the embedding service is available.

5. Keep the next steps separate

Stop and restart

Stop the application with Ctrl+C. Start it again using ./scripts/dev.sh. The database volume retains its data. Stop the database with docker compose -p vendune stop; do not remove the volume if you need its data.

Use a separate instance

On a fresh checkout, choose a different database port, app address and Compose project:

DB_PORT=15489 QDRANT_PORT=16335 BIND_ADDR=127.0.0.1:8789 \
COMPOSE_PROJECT_NAME=vendune-second ./scripts/dev.sh

For an existing .env, update DATABASE_URL to match the database port. Reuse the chosen project and ports on restart. See the repository quickstart for troubleshooting.