Quick start

A working install with a realistic demo Institution, in about five minutes, using Docker.

This gets the whole stack running on one machine with demo data in it, so you can see the live visitor list full rather than empty. It is an evaluation path, not a deployment. For a real install read Install.

Before you start

Docker Engine 24 or newer, with the Compose plugin. Docker Desktop is fine for this.
About 4 GB of RAM free and 20 GB of disk.
Nothing else. PostgreSQL, Redis and nginx all come in the stack.

Three commands

Clone and start

git clone <repository> taifa-support
cd taifa-support
 
make dev

make dev creates .env from .env.example, builds the images, starts postgres, redis, backend, worker, frontend, nginx and the one-shot widget builder, and then follows the logs. make up does the same detached.

Create the schema

make migrate

This creates the 56 tables.

Migrating is a separate step on purpose. The stack starting and the schema changing are different events, and a deployment that silently migrates on boot is one that can corrupt a database because a container restarted at the wrong moment.

Load the demo Institution

make seed

This creates one demo Institution with 40 visitors, live sessions, conversations, tickets and a knowledge base, and prints the sign-in address and password.

The seed is idempotent. Run it again and you get the same demo, not a second copy. It only ever touches the Institution whose slug is demo-lands, so it is safe to run on an install that already has a real tenant. Delete it from the Institutions list when you are done.

Then open http://localhost:8080.

If a port is already taken

Override it in .env rather than editing the compose file:

.env

POSTGRES_PORT=5432
REDIS_PORT=6379
BACKEND_PORT=8000
FRONTEND_PORT=3000
HTTP_PORT=8080

Every service binds 127.0.0.1:<port>, so these are host-side bindings only and nothing is reachable from another machine. The one exception is nginx, which is the only thing meant to answer from outside. See the port map.

Without Docker

For backend development, when you want a reload loop rather than a container:

cd backend
python3.12 -m venv venv && ./venv/bin/pip install -r requirements.txt
export DATABASE_URL=postgresql+asyncpg://taifa:taifa@localhost:5432/taifa_support
./venv/bin/alembic upgrade head
./venv/bin/uvicorn app.main:app --reload

You still need a PostgreSQL and, above one process, a Redis. Redis is not optional past a single backend worker: presence and the websocket fan-out both live there, so without it an agent connected to worker A never sees an event raised on worker B.

The commands worth knowing

make dev       # start the development stack, following logs
make up        # the same, detached
make down      # stop and remove containers
make build     # rebuild images
make logs      # follow every service
 
make migrate                  # apply pending migrations
make revision msg="add x"     # autogenerate a new one
make seed                     # load the demo Institution (idempotent)
 
make test      # backend test suite
make lint      # ruff + mypy
 
make deploy    # build, migrate and restart the production stack, on the server

The first-run wizard, which is what you meet on a real install with no demo data.
Install the widget on a portal so real visitors start appearing.
Install for the production path.