Sign In
Appendices · #E

Contributing Guidelines & Getting Started

Reading Progress79%

Appendix E: Contributing Guidelines & Getting Started

This guide compiles instructions from across the workspace to help you run the development environment manually using split terminals in your preferred IDE (e.g., VSCode).

1. Start Backing Services (Docker)

Make sure Docker Desktop is open and running, then execute the following command from the repository root:

docker-compose up -d postgres redpanda clickhouse otel-collector

2. Start Django Backend Services

Open 4 separate split terminals in your editor, navigate to backend/, activate the virtual environment, and run each command:

Setup (First-time only)

If you haven't set up the Python virtual environment or applied migrations yet:

cd backend
cp .env.example .env
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser

Tab A: Django API Server

cd backend
source .venv/bin/activate
python manage.py runserver

Tab B: Telemetry Worker

Required to consume telemetry events from Redpanda and save them to the database so your dashboard stats load.

cd backend
source .venv/bin/activate
python manage.py telemetry_worker

Tab C: ML Worker

Required to run PyTorch training runs in a decoupled process to calculate SLA and threat anomaly forecasts.

cd backend
source .venv/bin/activate
python manage.py ml_worker

Tab D: Security Worker

cd backend
source .venv/bin/activate
python manage.py security_worker

3. Start Frontend Client (Angular)

In a new terminal window or split:

Setup (First-time only)

cd frontend
cp .env.example .env  # Add your actual Firebase configurations here
npm install --legacy-peer-deps

Run Server

cd frontend
npm start

The client will be hosted at http://localhost:4200/.

4. Start Marketing Site (Astro)

In a new terminal window or split:

Setup (First-time only)

cd marketing
npm install

Run Server

cd marketing
npm run dev

The marketing site will be hosted at http://localhost:4321/.

5. Start Sanity Studio (CMS)

In a new terminal window or split:

Setup (First-time only)

cd studio
npm install

Run Server

cd studio
npm run dev

The studio interface will be hosted at http://localhost:3333/.

6. Troubleshooting & Maintenance

Resetting Python Environment

cd backend
deactivate
rm -rf .venv
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Resetting Frontend/Studio/Marketing NPM Dependencies

If you encounter dependency issues or slow installs, reset the NPM tree:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install --legacy-peer-deps

7. Local Mock Authentication

When developing locally, you can bypass the cloud Firebase Authentication backend and run completely offline:

  1. In the frontend/.env file, leave the Firebase API Key as PLACEHOLDER_API_KEY.
  2. When the frontend starts, it detects this placeholder and enables mock authentication mode automatically.
  3. You can log in with any username/email and password:
    • Security Admin (full access): Use email [email protected] (any password).
    • Operator (standard access): Use any other email or username.
  4. When settings.DEBUG = True, the backend Django API server intercepts the mock tokens and automatically creates/logs in the corresponding Django user profile.