Quick Start

Get Stoa running locally in under 5 minutes.

Option A: Docker (recommended)

Everything you need is Docker. No Go or Node.js required.

1. Clone the repository

git clone https://github.com/stoa-hq/stoa.git
cd stoa

2. Create configuration

cp config.example.yaml config.yaml

The default values work out of the box with Docker Compose — no changes required.

3. Start everything

docker compose up -d

This starts PostgreSQL and the Stoa application. On the first run the Docker image is built (including admin and storefront frontends), which takes a few minutes.

4. Set up the database

# Run migrations (create tables)
docker compose exec stoa ./stoa migrate up

# Create an admin user
docker compose exec -it stoa ./stoa admin create --email admin@example.com

# Optional: load demo data (products, categories, etc.)
docker compose exec stoa ./stoa seed --demo

5. Open the app

What	URL
Storefront	http://localhost:8080
Admin Panel	http://localhost:8080/admin
API Health Check	http://localhost:8080/api/v1/health

Log into the admin panel with the credentials from step 4.

Production Deployment

This guide is for local development. For production deployments, Stoa must run behind a reverse proxy (nginx, Caddy) with TLS. See Self-Hosting Guide.

Stopping and restarting

docker compose down          # Stop (data is preserved)
docker compose down -v       # Stop and delete all data
docker compose up -d         # Restart

---

Option B: Local Development (without Docker for the app)

For working on the codebase it is more convenient to run only PostgreSQL via Docker and execute the app directly.

Prerequisites

Tool	Version
Go	1.23+
Node.js	20+
Docker	latest

1. Start PostgreSQL

docker compose up -d postgres

2. Create configuration

cp config.example.yaml config.yaml

3. Set up the database

go run ./cmd/stoa migrate up
go run ./cmd/stoa admin create --email admin@example.com
go run ./cmd/stoa seed --demo   # optional

4. Build frontends

Both admin and storefront are SvelteKit applications embedded into the Go binary via //go:embed. They must be built before the first run:

cd admin && npm install && npm run build && cd ..
cd storefront && npm install && npm run build && cd ..

Important: After every change to the frontends you must run npm run build AND rebuild the Go binary, because the frontends are statically embedded into the binary.

5. Start the backend

go run ./cmd/stoa serve

Or as a compiled binary:

go build -o stoa ./cmd/stoa
./stoa serve

Frontend development with hot-reload

For frontend development you can start the Vite dev servers, which provide hot-reload:

cd admin && npm run dev       # Admin panel (port 5174)
cd storefront && npm run dev  # Storefront (port 5173)

The dev servers communicate with the Go backend on port 8080 via the API. Make sure the backend is running.

---

Installing the Binary Globally

After building, you can install the stoa binary to ~/.local/bin so you can run it from anywhere without ./bin/stoa:

make install

This builds the full binary (frontends + Go) and copies it to ~/.local/bin/stoa. Make sure ~/.local/bin is in your $PATH:

# Add to ~/.bashrc or ~/.zshrc if not already present
export PATH="$HOME/.local/bin:$PATH"

You can override the install location:

make install INSTALL_DIR=/usr/local/bin

Linux & macOS only

make install targets Linux and macOS. Windows users should use Docker or build the binary manually with go build.

---

Makefile Commands

make build              # Build frontends + compile Go binary
make run                # build + start
make install            # Build + install binary to ~/.local/bin
make test               # Run Go tests
make test-race          # Tests with race detector
make lint               # Run linters (golangci-lint + go vet)
make docker-up          # docker compose up -d
make docker-down        # docker compose down
make admin-dev          # Admin frontend dev server
make storefront-dev     # Storefront dev server
make seed               # Load demo data
make mcp-store-build    # Build Store MCP Server binary
make mcp-admin-build    # Build Admin MCP Server binary

Next Steps

• Configuration — customize Stoa for your environment
• API Overview — authentication and endpoints
• MCP Setup — connect an AI agent to your shop
• Plugin System — extend Stoa with plugins