Skip to content

README.md

Latest commit

 

History

History
204 lines (144 loc) · 4.85 KB

README.md

File metadata and controls

204 lines (144 loc) · 4.85 KB

ARGUS (VPS Deployment)

ARGUS is a geospatial intelligence platform running on a VPS with a Dockerized multi-service backend and a Next.js/Cesium frontend.

This repository is the canonical source of truth for:

  • application code (argus-app, argus-api, ingestor)
  • infrastructure (docker-compose.yml, nginx, cloudflared, infra)
  • operational docs (docs, VPS_CHANGELOG_AND_NEXT_STEPS.md)

Architecture Overview

ARGUS runs as containers on a VPS (single host deployment):

  • nginx (argus_nginx)
    Reverse proxy / edge entrypoint.
  • argus-app (argus_app)
    Next.js frontend + API routes for feed proxies.
  • argus-api (argus_api)
    Express backend (analytics, health, server APIs).
  • postgis / timescaledb (argus_postgis)
    Primary database.
  • titiler (argus_titiler)
    Raster tile serving.
  • ingestor (argus_ingestor)
    Scheduled ingest/processing jobs (e.g., GFS).
  • cloudflared (argus_cloudflared)
    Cloudflare Tunnel to expose services securely.

All services communicate on argus_network.

Service Map

User-facing path

  1. Internet traffic enters through Cloudflare Tunnel / DNS.
  2. cloudflared forwards traffic to nginx.
  3. nginx routes:
    • / -> argus-app
    • /spatial/* -> Zerve-hosted spatial FastAPI app
    • /api/feeds/* -> argus-app proxy routes
    • /api/* -> argus-api
    • /tiles/* -> titiler

Data path

  • ingestor writes raster outputs to data/tiles.
  • argus-api advertises available analytics layers.
  • titiler serves those raster files as tile endpoints.
  • argus-app renders overlays in Cesium.

Feeds / Integrations

Current feed integrations include:

  • OpenSky commercial flights
  • ADS-B military flights
  • CelesTrak satellites
  • USGS earthquakes
  • TFL CCTV + webcam sources
  • Cloudflare Radar outages
  • AlienVault OTX threat pulses
  • FRED macro feed
  • AISStream vessel snapshot

Most third-party feeds are proxied through server routes to avoid browser CORS/API key exposure.

Repo Layout

argus/
  argus-app/         # Next.js app + Cesium UI + feed proxy routes
  argus-api/         # Express API service
  ingestor/          # Data ingestion/processing jobs
  nginx/             # Nginx config
  cloudflared/       # Cloudflare tunnel config
  infra/             # DB init / infra assets
  data/              # Local data mounts (tiles, etc)
  docs/              # Architecture plans and technical notes
  docker-compose.yml

Running on VPS (Docker)

1) Prerequisites

  • Docker + Docker Compose plugin installed
  • .env file present at repo root (never commit secrets)

2) Start stack

docker compose up -d --build

3) Check health

docker compose ps
docker compose logs -f --tail=100

4) Stop stack

docker compose down

Common Operations

Rebuild only app/api

docker compose up -d --build argus-app argus-api

Restart a single service

docker compose restart argus-app

Open container shell

docker compose exec argus-app sh
docker compose exec argus-api sh

Verify API from inside network

docker compose exec -T argus-api node -e "fetch('http://localhost:3001/api/health').then(r=>r.text()).then(console.log)"

Environment Variables

Primary runtime env file: .env (repo root)

Important keys include (non-exhaustive):

  • CESIUM_ION_TOKEN
  • CLOUDFLARE_RADAR_TOKEN
  • OTX_API_KEY
  • FRED_API_KEY, FRED_SERIES_ID
  • AISSTREAM_API_KEY, AISSTREAM_ENDPOINT
  • OPENSKY_CLIENT_ID, OPENSKY_CLIENT_SECRET
  • POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
  • CORS_ORIGIN (comma-separated allowlist for argus-api)
  • GlitchTip / Sentry DSNs

Do not commit secret-bearing files. .gitignore excludes local env variants.

Development Notes

  • Frontend-specific docs: argus-app/README.md
  • Infra updates and incident notes: VPS_CHANGELOG_AND_NEXT_STEPS.md
  • Large architecture/design proposals: docs/plans/*

Git / Branching Expectations

  • master is actively used for deployment work.
  • Keep commits focused and operationally readable.
  • Avoid committing local secret files (.env*, credentials, backup configs).
  • Verify git status before push.

Troubleshooting Quicklist

  1. docker compose ps -> confirm all services are up.
  2. docker compose logs <service> -> inspect errors.
  3. Verify route flow: Cloudflare -> nginx -> target service.
  4. Verify tiles path consistency: /data/tiles mounted where expected.
  5. Validate env keys are present when feed routes return auth errors.

Security Notes

  • Secrets in chat should be rotated and reissued.
  • Never hardcode API keys in source.
  • Keep credentials in .env or secret manager only.
  • Remove stale .bak / scratch config artifacts from commits.

If you are onboarding to this repo, read AGENTS.md next.