Terranoetis runs in a Docker Compose stack with three services, or directly with Node.js for development. This document covers setup, configuration, production deployment, and CI/CD.
Table of Contents
Prerequisites
Quick Start (Development)
# Clone and install
git clone https://github.com/sreyassanker/Terranoetis.git
cd Terranoetis
cp .env.example .env # Fill in API keys as needed
npm install
# Start development servers
npm run dev
# In a separate terminal:
npm run dev:client # Vite dev server (port 3000) only
npm run dev:server # Express API (port 3001) only
The dev command starts the Vite dev server and the Express API concurrently. Redis is started automatically if installed; otherwise the server falls back to SQLite.
Verification
# Frontend
open http://localhost:3000
# API health
curl http://localhost:3001/api/health
Docker Deployment
Services
In production (NODE_ENV=production), the Express app serves the built frontend from dist/ on the same origin as the API — open http://localhost:3001 for the full application. In development, Vite serves the client on :3000 and proxies /api to :3001.
Production Start
# Copy environment (edit with your production values)
cp .env.example .env
# Build and start all services
docker compose up -d
# Verify
curl http://localhost:3001/api/health # API
open http://localhost:3001 # Frontend (served by the same container)
# View logs
docker compose logs -f terranoetis
Build
docker compose build # Rebuild images
docker compose up -d # Restart with rebuilt images
Data Persistence
Configuration
Ports
NODE_ENV Behavior
Environment Variables
The .env file configures 100+ variables covering 70+ integrated services (see .env.example). Missing keys disable the corresponding feature — services degrade gracefully.
Required (production)
Category Reference
Kaggle simulation kernels (optional setup)
Four physics simulations (tsunami, volcano, landslide, flood) are dispatched to Kaggle kernels as their execution venue. All kernels are NumPy CPU code (no GPU imports); only flood-sim requests Kaggle's GPU accelerator in its kernel metadata, so “GPU kernels” is a hosting term here, not a compute claim (verified — see modes table). The three 2D scenarios — earthquake, wildfire, and hurricane — finish in seconds on a laptop CPU and run locally via python3 (see server/kaggle/simRunner.ts; measured end-to-end job completion of 166 ms for the earthquake kernel), so they work without any token. To enable the Kaggle-routed kernels:
- Create a token at https://www.kaggle.com/settings/account → Create New Token (requires an account with phone verification).
- Save the downloaded
kaggle.json as ~/.kaggle/kaggle.json and restrict permissions:
mkdir -p ~/.kaggle && mv ~/Downloads/kaggle.json ~/.kaggle/kaggle.json && chmod 600 ~/.kaggle/kaggle.json
- Install the Kaggle CLI (
pip install kaggle), or point KAGGLE_BIN at its path.
The simulation runner reads credentials exclusively from ~/.kaggle (KAGGLE_CONFIG_DIR, see server/kaggle/simRunner.ts) — never from the repository, so no secrets are ever committed. Without a token, the 4 Kaggle-routed simulations disable gracefully while the 3 local CPU scenarios (earthquake, wildfire, hurricane) and the analytical engine keep working.
CI/CD Pipeline
The GitHub Actions workflow (.github/workflows/ci.yml) runs the following on pushes and pull requests targeting main/develop; the documentation gate ships as a separate workflow (.github/workflows/docs.yml):
CI Notes
- Node version: 20 (specified in workflow and
.nvmrc; the verification pass ran Node 26 with 1,653 unit + 49 integration tests passing)
- Docs quality gate:
.github/workflows/docs.yml runs on pushes/PRs to main/develop touching docs/site/**, scripts/docs/**, README.md, CONTRIBUTING.md, SECURITY.md, or the workflow itself; deploy-docs.yml publishes docs/site/ to GitHub Pages (workflow deploy; also manually dispatchable)
- Browser tests run headless in CI on
ubuntu-latest using Chromium with software WebGL (--use-gl=angle --enable-unsafe-swiftshader), so no physical display/GPU is required. They are still the most environment-sensitive job and can be flaky.
- Redis is optional in both development and CI (the server falls back to SQLite gracefully)
- Docker Compose is recommended for production
Security
Best Practices
- Always set a strong JWT_SECRET and ADMIN_BOOTSTRAP_PASSWORD in production
- Keep the .env file out of version control (gitignored)
- Periodically rotate API keys
- Seal the Docker network if deploying in a multi-tenant environment
