🛰️ Mission Control: ISS Tracker

A production-grade, full-stack dashboard for tracking the International Space Station in real-time. This project combines orbital mechanics (SGP4 propagation), a background worker architecture, and a resilient Next.js frontend.

🚀 The Stack

Frontend: Next.js 15 (App Router) + Tailwind CSS + Lucide Icons
Backend/Worker: Node.js + satellite.js (Orbital Physics)
Database: SQLite (better-sqlite3)
Infrastructure: Docker & Docker Compose
CI/CD: Woodpecker CI
Deployment: Hetzner VPS + Caddy (Reverse Proxy)

🏗️ Architecture

The system is split into two distinct services that share a persistent SQLite volume:

The Worker (iss-worker):
- Fetches Two-Line Element (TLE) data from CelesTrak.
- Performs SGP4 propagation to calculate ISS coordinates.
- Determines upcoming "Pass Windows" (AOS to LOS) relative to a fixed ground station.
- Updates the shared database with the next two valid passes.
The Web App (mc-web):
- Server-side queries the database for the next future pass.
- Calculates real-time "T-Minus" countdowns.
- Triggers a "Live" state when the ISS is above the horizon.
- Uses router.refresh() with a useRef lock to transition between passes without page reloads.

🛠️ Key Technical Solutions

Orbital Propagation

Instead of relying on 3rd-party APIs for pass predictions, this project runs its own physics engine. Using satellite.js, it calculates the elevation of the ISS relative to the observer's latitude and longitude.

Self-Healing Database

The database includes an automatic migration layer in lib/db.ts. On startup, the application inspects the SQLite schema and applies necessary ALTER TABLE commands, ensuring seamless updates during CI/CD deployments without manual intervention.

Resilient Synchronization

To prevent infinite refresh loops in the Next.js frontend, the EventCard component implements a "Refresh & Quiet" logic. It uses a useRef to ensure that only one server-side data sync is requested per orbital event.

📦 Deployment

Docker Multi-Platform Build

The images are explicitly built for the linux/amd64 architecture to ensure compatibility with Node.js native modules (like better-sqlite3) on the Hetzner VPS.

docker buildx build --platform linux/amd64 -t mission-control-web .

Woodpecker CI

The pipeline is automated via .woodpecker.yaml, handling the build, registry push, and remote deployment via Docker Compose.

🚦 Getting Started

Clone the repo
Install dependencies: npm install
Run the worker: npx tsx scripts/update-space.ts
Start the dashboard: npm run dev

Ground Station Coordinates: 55.6761° N, 12.5683° E

2.7 KiB Raw Permalink Blame History