Skip to content

Getting started

How to run TowitLinks on your own machine. Each component can run on its own; you only need the backend if you are touching the console or the mobile app.

Prerequisites

  • Docker and Docker Compose
  • Python 3.11
  • Node 18 or newer, with pnpm for frontend/ and landing/
  • A Twilio account, a Firebase project and a Stripe test account if you intend to exercise calls, live updates or billing

Credentials are not in the repository

backend/google_credentials.json and the Android keystore are no longer tracked. Ask a maintainer for them, and never commit them back. See Known issues.

Backend

The development compose file starts the infrastructure only — PostgreSQL on 5433 and RabbitMQ — and expects you to run Django yourself, so you keep the reloader and the debugger.

cd backend
cp .env.example .env            # then fill it in, see Configuration
docker compose -f docker-compose-dev.yml up -d

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver 0.0.0.0:8000

The API is then at http://127.0.0.1:8000/api/v1 and the Django admin at http://127.0.0.1:8000/admin/.

Point DB_PORT at 5433 to match the dev container. Read Configuration before filling in .env — several variables in .env.example are stale and a few that the code needs are missing from it.

Note

The celery_worker and celery_beat services in the compose files do nothing; there is no task code in the backend. Background jobs are HTTP endpoints — see Known issues.

Web console

cd frontend
pnpm install
cp .env.example .env            # see the note below
pnpm dev                        # vite --host --port 5001

Open http://localhost:5001.

Set VITE_API_URL=http://127.0.0.1:8000/api/v1. The Firebase keys must be named PUBLIC_FIREBASE_*, not the VITE_FIREBASE_* spelling that .env.example uses — the code reads them through $env/static/public (frontend/src/lib/actions/firebase/FirebaseApp.ts:9-27). Without them the application will not start, because Firestore drives every live update.

Other useful commands:

pnpm validate      # svelte-check
pnpm storybook     # component workshop on :6006
pnpm build:app     # static bundle into build/

There is no lint, test or format script, even though ESLint, Prettier, Vitest and Playwright are all installed.

Landing

cd landing
pnpm install
pnpm dev

Its two forms post to https://app.towitlinks.com — production — because the URL is hardcoded (landing/src/routes/+page.server.ts:9). Do not submit test data through them.

Mobile

Build the web bundle first, then sync Capacitor:

cd frontend
pnpm build:android     # vite build && cap sync android && cap open android

For on-device hot reload, uncomment the server.url block in frontend/capacitor.config.ts:21-28 and point it at your machine — http://10.0.2.2:5001 for the Android emulator, your LAN IP for a physical device or iOS. Remove it again before building anything you intend to ship.

Full APK and AAB production builds run on a dedicated host; see Mobile builds.

Running the whole stack in Docker

rebuild_and_run.sh at the repository root builds and starts the backend and the frontend from their production compose files and runs migrations. It assumes it is executed from a parent directory containing a VoIP checkout and it begins with a git pull, so it is a server-side script, not a local convenience. The same caveat applies to deploy.sh and the other rebuild_and_run_*.sh scripts — see Deployment.

Where to go next