# Run guide

How to set up and run the Meetings backend on your own machine. Commands are for Windows
PowerShell, run from the project folder. No Docker is needed.

## One-time setup

**1. Install**
- Python 3.11 or newer
- PostgreSQL 16 or newer (note the `postgres` password you choose during install)

**2. Download LiveKit server v1.13.11** (a single program, nothing to install):

```powershell
Invoke-WebRequest https://github.com/livekit/livekit/releases/download/v1.13.11/livekit_1.13.11_windows_amd64.zip -OutFile "$env:USERPROFILE\livekit.zip"
Expand-Archive "$env:USERPROFILE\livekit.zip" -DestinationPath "$env:USERPROFILE\livekit"
& "$env:USERPROFILE\livekit\livekit-server.exe" --version    # should print 1.13.11
```

**3. Create the database user and databases** (asks for the `postgres` password; adjust the
path if your PostgreSQL version is not 18):

```powershell
& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U postgres -h localhost -c "CREATE ROLE livekit_meetings LOGIN PASSWORD 'livekit_meetings';" -c "CREATE DATABASE livekit_meetings OWNER livekit_meetings;" -c "CREATE DATABASE livekit_meetings_test OWNER livekit_meetings;"
```

`livekit_meetings` is for running the app; `livekit_meetings_test` is for the tests.

**4. Create the virtual environment and install the dependencies**

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
```

**5. Create your `.env`** (never commit it):

```powershell
Copy-Item .env.example .env
```

Fill in the blanks using the comments in the file. For local use:

```
DATABASE_URL=postgresql+asyncpg://livekit_meetings:livekit_meetings@localhost:5432/livekit_meetings
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=<the value next to devkey under keys: in livekit.yaml>
```

**6. Create the database tables**

```powershell
alembic upgrade head
```

Run this again whenever you pull changes that add migrations.

## Run the app (every time)

Use two terminals.

**Terminal 1: LiveKit**

```powershell
& "$env:USERPROFILE\livekit\livekit-server.exe" --config livekit.yaml
```

**Terminal 2: the backend**

```powershell
.\.venv\Scripts\Activate.ps1
uvicorn app.main:create_app --factory --reload --port 8001
```

Wait for `Uvicorn running on http://127.0.0.1:8001`. `--reload` restarts the server
whenever you save a code file.

## See the APIs

| URL | What it is |
|---|---|
| http://localhost:8001/docs | Interactive API page: pick an endpoint, **Try it out**, **Execute** |
| http://localhost:8001/redoc | The same API as read-only documentation |
| http://localhost:8001/health | `200` when the database and LiveKit are reachable, `503` with the failing part `down` otherwise |

## Stop

Press `Ctrl+C` in each terminal. If a terminal was closed and LiveKit is still running in the
background, stop it from any PowerShell with `Stop-Process -Name livekit-server`.

## Tests and lint

There is no CI pipeline: run these before every push and put the result in the merge
request description.

```powershell
.\.venv\Scripts\Activate.ps1
pytest
ruff check .
ruff format --check .
```

Tests need PostgreSQL running (they use `livekit_meetings_test`) but not LiveKit.

## Troubleshooting

| Problem | Fix |
|---|---|
| PowerShell refuses to run `Activate.ps1` | Run once: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |
| `password authentication failed for user "livekit_meetings"` | Step 3 was not run, or `DATABASE_URL` in `.env` is wrong |
| `/health` shows `"database": "down"` | Check the PostgreSQL service is running (`Get-Service postgresql*`) |
| `/health` shows `"livekit": "down"` | Terminal 1 is not running, or the key/secret in `.env` don't match `livekit.yaml` |
| LiveKit logs `CPU monitoring unsupported on current platform` | Harmless on Windows; ignore it |
| `address already in use` / port 8001 or 7880 busy | Another copy is still running; stop it. We use 8001 because 8000 is often taken by another local app; LiveKit's webhook in `livekit.yaml` points at 8001, so keep the two the same |