63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# 🛰️ 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:
|
|
|
|
1. **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.
|
|
2. **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.
|
|
|
|
```bash
|
|
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 |