Skip to main content

Setup Guide

This guide provides discrete, ordered instructions for installing, configuring, and launching the JERC Sentry platform from scratch.

JERC Sentry consists of three primary layers:

  1. Backend: A FastAPI server managing telephony and AI logic.
  2. Mobile App: A Flutter-based dashboard for Protectors.
  3. Protectee Device: Native configuration on an iPhone.

Prerequisites​

Before starting, ensure your development environment meets the following requirements:

Software​

  • Python 3.14+ & pip
  • Flutter SDK (Latest stable version)
  • Docker & Docker Compose
  • Cloudflared (For local webhook tunneling)
  • Firebase CLI
  • tmux (Required for the automated backend start script)

Required Accounts & API Keys​

You will need to retrieve API keys from the following services:

  • Telnyx: API key and UUID from a preconfigured Voice API Application.
  • Deepgram: API key for real-time transcription.
  • Groq: API key for Llama 3.1 inference.
  • Firebase: A project with Authentication and Cloud Messaging enabled.
  • GitHub: A Personal Access Token (PAT) with repo scope for bug reporting.

Step 1: Repository Setup​

Clone the JERC Sentry monorepo to your local machine.

git clone git@github.com:dcsil/jerc-code.git
cd jerc-code

Step 2: Backend Configuration​

The backend handles the core logic of the system. Follow these steps to configure your environment. For further reference, see backend/README.md.

1. Initialize Virtual Environment​

Navigate to the backend/ directory and install dependencies.

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/dev.txt

2. Configure Environment Variables​

Copy the example environment file and fill in your API keys.

cp .env.example .env

Key Variables to Populate:

  • TELNYX_API_KEY, GROQ_API_KEY, DEEPGRAM_API_KEY: Your API keys for each respective platform.
  • GH_TOKEN: Your GitHub PAT.
  • CLOUDFLARE_TUNNEL_TOKEN: Your tunnel authentication token.

3. Firebase Service Account​

  1. Go to the Firebase Console > Project Settings > Service Accounts.
  2. Click Generate new private key.
  3. Create a credentials/ folder.
  4. Save the JSON file as service-account-dev.json inside that folder.

Step 3: Launching the Backend​

We provide an automated script to launch the full backend stack (Database, API, and Tunnel) in a synchronized environment.

./scripts/start.sh

Expected Output:

A tmux session will open with three panes:

  • Left: The FastAPI server (Uvicorn). Look for Application startup complete.
  • Top-Right: PostgreSQL database initializing.
  • Bottom-Right: Cloudflare tunnel status.

Validation:

Open http://localhost:8000/docs in your browser. You should see the Swagger UI documentation.

Step 4: Mobile App Configuration​

The Protector app is built with Flutter and communicates with the backend. For further reference, see mobile/README.md.

1. Install Flutter Packages​

Navigate to the mobile/ directory and pull dependencies.

cd ../mobile
flutter pub get

2. Configure Environment Variables​

Copy the example environment file.

cp .env.example .env

Ensure DEV_BACKEND_URL is set to https://api.jercsolutions.me.

Step 5: Launching the Mobile App​

Ensure you have an Android or iOS Emulator running. Then, run the following startup script:

./scripts/start.sh

Expected Output:

The Flutter application will build and launch on your active emulator. You should see the Login screen.

Validation:

Click on the Sign up page and create a new account. If successful, you will be redirected to the Protector Dashboard.

Next Steps​

At this point, the initial setup for JERC Sentry is complete. For detailed instructions on how to use the service and configure the Protectee Device, please refer to the Usage Guide.

Troubleshooting​

IssuePotential CauseResolution
Backend script failstmux not installedInstall tmux: brew install tmux or sudo apt install tmux.
403 Forbidden on DialTelnyx Outbound ProfileEnsure your Telnyx App is linked to an Outbound Profile with US/Canada permissions.
Tunnel not connectingInvalid TokenRe-request a CLOUDFLARE_TUNNEL_TOKEN from a lead developer or check the Cloudflare dashboard.
No Push NotificationsFCM configuration or emulator limitations1. Firebase: Confirm service-account-dev.json is correctly placed and mapped in .env. 2. Android: Use an emulator with Google Play Services. 3. iOS: Notifications are unavailable on emulators due to Apple's paid developer account requirements.
CCF Registration FailedCarrier RestrictionsSome carriers require specific MMI codes. Verify the code string in the Protector app.