This repository contains two services:

• Backend API (FastAPI) under Backend/api/
• Frontend UI (Flask) under Frontend/

A root-level docker-compose.yml builds and runs both services together.

• Docker Desktop (or Docker Engine) installed
• Docker Compose v2 (bundled with recent Docker Desktop)
• Terminal access

If you're new to Docker, think of images as "apps" you build, and containers as the running "instances" of those apps.

• Backend/api/Dockerfile: Builds the API image
• Frontend/Dockerfile: Builds the UI image
• docker-compose.yml: Orchestrates API and UI
• .env: Environment variables loaded by Compose

First time setup - copy the template to create your .env file:

cp ".env copy" .env

The default configuration has authentication disabled for easy local development (DISABLE_AUTH=true). This is perfect for getting started!

Build and start both services:

docker compose up -d --build

• API: http://localhost:8000
• Frontend UI: http://localhost:9001
• API Docs: http://localhost:8000/api/v1/docs

docker compose down

1. Build images (compiles dependencies and copies code):

docker compose build

2. Start containers:

docker compose up -d

3. Verify they are running:

docker ps

4. Check logs (live streaming):

docker logs -f jarvis-api
# in a second terminal
docker logs -f jarvis-frontend

5. Test endpoints:

# API root
curl http://localhost:8000
# API health
curl http://localhost:8000/api/v1/health
# Open the UI in your browser
open http://localhost:9001

The .env file controls both services. Copy from .env copy if you haven't already:

cp ".env copy" .env

By default, authentication is disabled for local development:

• DISABLE_AUTH=true - No API keys required (recommended for local dev)
• BACKEND_API_KEY - Not needed when auth is disabled

For production, enable authentication:

DISABLE_AUTH=false
API_KEYS_ADMIN=your-secure-admin-key
BACKEND_API_KEY=your-secure-admin-key  # Frontend uses this to talk to backend

• HEC Batching (used by UI when sending to HEC):
  • S1_HEC_BATCH=true
  • S1_HEC_BATCH_MAX_BYTES=1048576
  • S1_HEC_BATCH_FLUSH_MS=500
  • S1_HEC_DEBUG=0
• Secret Key: SECRET_KEY - Change for production deployments

After editing .env, restart containers:

docker compose down && docker compose up -d

• Rebuild everything after Dockerfile changes:

docker compose build --no-cache && docker compose up -d

• Rebuild just the API:

docker compose build api && docker compose up -d

• Rebuild just the Frontend:

docker compose build frontend && docker compose up -d

• Tail logs:

docker logs -f jarvis-api

Symptom: Frontend shows "Failed to save destination" with 403 errors about missing API key.

Solution: Create the .env file with DISABLE_AUTH=true:

cp ".env copy" .env
docker compose down && docker compose up -d

Another process is using that port. The UI maps 9001:8000. Either stop the other app or change the left number in docker-compose.yml.

Rebuild the API image:

docker compose build api --no-cache && docker compose up -d

The image includes symlinks for these paths; ensure you rebuilt after recent changes.

Inside containers, the UI uses API_BASE_URL=http://api:8000. From your host, use http://localhost:8000 for the API and http://localhost:9001 for the UI.

• Live code mounting is enabled for the UI and backend content in Compose (read-only) to keep container images small and consistent. Rebuild images when you change Dockerfiles or dependencies.
• Use docker compose down to stop and clean up containers and network.

Stop and remove containers, and the compose network:

docker compose down

Optionally remove images:

docker rmi jarvis_frontend-api jarvis_frontend-frontend