POS2 is built for restaurants and venues that want:

• One place for operations — Orders, tables, reservations, and the menu in a single stack.
• Customer ordering without apps — Guests scan a table QR code and browse the menu. An optional table PIN limits who can order.
• Real-time updates — Order status (pending → preparing → ready → delivered → paid) reaches staff and guests over WebSockets.
• Multi-tenant from day one — Each restaurant (tenant) has isolated data, settings, and its own payment setup.
• Self-hosted — Run on your own server or local network. There is no vendor lock-in.

You do not need the full POS on day one. Start with one public feature and add the rest when you are ready. Other areas stay in the same tenant. Turn them on in Settings → Navigation when you need them.

The digital QR menu is part of every plan. On self-host (AGPLv3) there is no license fee. On hosted Satisfecho you get a free trial with no card required. Live prices are on the Public pricing row below.

1. Register your restaurant (Getting Started below).
2. Add items under Products in the staff app.
3. Create tables under Tables and open each table’s QR code (print or display it).
4. Guests scan the code and browse /menu/{table_token}. They do not install an app.

Add later when you want: table PIN, online checkout, kitchen display, and inventory. URLs are in Access Points.

Use online booking without the full order flow.

1. Register and sign in (see Getting Started).
2. Turn on Reservations & guest feedback under Settings → Navigation if it is not already enabled.
3. Share /book/{tenantId}.
4. Staff manage bookings at /reservations.

Guests can join the waiting list at /waitlist/{tenantId} (linked from the book page). Staff and guest flows: the Reservations row below.

Staff dashboard, kitchen display, and customer menu — a quick visual sense of the product.

More screenshots (orders, reports, reservations, tables, provider portal) are listed in docs/screenshots/README.md.

Planned, not yet implemented: Order Phase 4 (batch operations, audit, item replacement) and a stricter “must pay before continuing” flow. Further security items (for example CAPTCHA after failed logins) are in ROADMAP.md.

• Frontend: Angular 21+ (SPA)
• Backend: FastAPI, SQLModel ORM
• Database: PostgreSQL 18
• Cache / pub-sub: Redis 7
• Real-time: WebSocket bridge (custom service)
• Deployment: Docker Compose, HAProxy

So, you really want to get your hands dirty and install? Then continue reading. If you want to try it out first, you may use the hosted version at satisfecho.de. No worries, anything you do on satisfecho.de — your data, your menus — you can export at any time and import the same on a self-hosted stack. Open source, no lock-in. ;-)

• Docker and Docker Compose
• Git

1. Clone the repository

   git clone https://github.com/satisfecho/pos
   cd pos

2. Configure environment

   cp config.env.example config.env

   Local defaults are enough to start. For production or a custom domain, set API_URL, WS_URL, CORS_ORIGINS, and SECRET_KEY. Use https:// and wss:// in production. See docs/0004-deployment.md. Variable meanings are in Configuration.

3. Start all services

   • Local (development): docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file config.env up -d
   • Production (e.g. amvara9): docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file config.env up -d

4. Find the app URL Run docker compose -f docker-compose.yml -f docker-compose.dev.yml ps (or with .prod.yml if you used prod). Read the PORTS column for haproxy (for example 0.0.0.0:4202->4202/tcp). The host port is the app URL. The route list is Access Points. If the port is not 4202, use that port in those URLs.

5. Create an account There is no pre-seeded user. Open /register on that host. Enter tenant name, email, and password. The first user becomes the tenant owner. Then sign in at the app URL.

Key variables in config.env (see config.env.example for the full list):

Settings also include business profile, contact (phone, email, address, Tax ID, CIF), and opening hours.

Each feature row links to its guide. The full index is docs/README.md. Release notes are in CHANGELOG.md.

Browser → Frontend (Angular) → Backend (FastAPI) → PostgreSQL
                                    ↓
                               Redis (pub/sub)
                                    ↓
                          WebSocket bridge → Browser (real-time)

Services (Docker Compose):

• haproxy — Single entry point; routes / to frontend, /api to backend, /ws to WebSocket bridge. Port from FRONTEND_PORT (default 4202).
• front — Angular SPA (dev server in container).
• back — FastAPI app (Uvicorn).
• ws-bridge — WebSocket server; subscribes to Redis and pushes order updates.
• db — PostgreSQL 18.
• redis — Cache and pub/sub.

• Port: docker compose -f docker-compose.yml -f docker-compose.dev.yml ps → PORTS for haproxy → use that host port in the browser.
• Logs: docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f (all); same -f list with logs --tail=50 back, logs --tail=80 front, logs --tail=30 haproxy.

See AGENTS.md for more detail.

After docker compose … up, run the FastAPI TestClient suite in the back container (uses Postgres; rate limits disabled for tests):

docker compose -f docker-compose.yml -f docker-compose.dev.yml exec -T back python3 -m pytest /app/tests -q

The suite includes small guards such as tests/test_settings_defaults.py (e.g. EMAIL_FROM default). Puppeteer UI scripts and reservation capacity tests are in docs/testing.md.

The front service bind-mounts ./front only, so the container has no .git. front/docker-entrypoint.sh runs get-commit-hash.js on start to refresh commit-hash.ts. ./run.sh exports COMMIT_HASH from the host repo (when unset) so the footer shows the current short hash. If you use docker compose directly, optionally run from the repo root: export COMMIT_HASH=$(git rev-parse --short HEAD) before up (see config.env.example).

Migrations live in back/migrations/ and run automatically on backend startup.

• Apply manually: docker compose -f docker-compose.yml -f docker-compose.dev.yml exec back python -m app.migrate
• Check pending: docker compose -f docker-compose.yml -f docker-compose.dev.yml exec back python -m app.migrate --check
• New migration: Use timestamped names, e.g. back/migrations/YYYYMMDDHHMMSS_description.sql. See back/migrations/README.md.

Do not edit existing migration files; add a new migration to change schema.

The Compose database publishes 127.0.0.1:${POSTGRES_PORT:-5433} → container port 5432 (see config.env). The superuser name is POSTGRES_USER (default pos), same as DB_USER for the app — not the conventional PostgreSQL role name postgres.

If docker logs pos-postgres shows FATAL: role "postgres" does not exist, a client (GUI, psql, or a copy-pasted DSN) is using username postgres. Point it at POSTGRES_USER / DB_USER and POSTGRES_PASSWORD / DB_PASSWORD from config.env instead.

Ad-hoc SQL: There is no relation restaurantorder. Orders live in "order" (quoted — SQL keyword), line items in orderitem, floor tables in "table". See docs/0033-postgres-adhoc-sql-table-names.md.

• Frontend and backend both reload on code changes when run via Docker Compose.

docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file config.env down

• Production: Set a strong SECRET_KEY and REFRESH_SECRET_KEY in config.env.
• CORS: Set CORS_ORIGINS to your real frontend origin(s); avoid * in production if possible.
• Database: Use strong credentials; do not commit config.env.
• Stripe: Use live keys in production. Set them per tenant in Settings.
• Rate limiting: Global and per-route limits (login, register, payments, public menu, uploads, admin/management) use Redis. See docs/0020-rate-limiting-production.md. Table PIN attempts stay rate-limited.

Copyright (C) 2025 POS2 contributors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

The full license text is in LICENSE (GNU Affero General Public License v3.0).