Skip to content
Craft

Quick Start

This guide gets Craft running on your machine. By the end, you will have a live dashboard showing satellites over your location, a working search index, and pass predictions for the ISS.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose
  • Git
  • About 2 GB of disk space (Docker images + Skyfield ephemeris data)

Setup

Section titled “Setup”

  1. Clone the repository

    Terminal window
    git clone https://git.supported.systems/warehack.ing/astrolock.git
    cd astrolock

  2. Create your environment file

    Terminal window
    cp .env.example .env

    Open .env and set your observer location. This is the position Craft uses for all pass predictions and “what’s up” calculations.

    .env
    # Your coordinates (decimal degrees)
    OBSERVER_LAT=36.0
    OBSERVER_LON=-86.0
    OBSERVER_ALT=200
    OBSERVER_NAME=Home
    OBSERVER_GRID=EM66

    See Observer Setup for how to find your coordinates and grid square.

  3. Start the dev environment

    Terminal window
    make dev

    This starts PostgreSQL (TimescaleDB), the FastAPI backend, the Astro frontend, and the Starlight documentation site. First run takes a few minutes to build images and download Skyfield ephemeris files.

  4. Run database migrations

    Terminal window
    make migrate

  5. Seed the database

    Terminal window
    make seed

    This fetches current TLEs from CelesTrak, loads celestial object catalogs, and populates satellite frequency data from SatNOGS. It takes about a minute.

  6. Open the dashboard

    Visit http://localhost:4321 in your browser.

    You should see:

    • A 3D globe with satellite orbits drawn over it
    • A “What’s Up” panel listing objects currently above your horizon
    • Observer information showing your configured location
    • Status indicators for the API, rotor connection, and TLE freshness

First things to try

Section titled “First things to try”

Now that Craft is running, here are a few things worth exploring.

Find the ISS

Section titled “Find the ISS”

Open the command palette with Ctrl+K (or Cmd+K on macOS) and type ISS. Select ISS (ZARYA) from the results — NORAD catalog number 25544. The globe will fly to the station’s current position and begin tracking it.

You can also hit it directly through the API:

Terminal window
curl http://localhost:8000/api/satellites/25544

Check upcoming passes

Section titled “Check upcoming passes”

With the ISS selected, the tracker panel shows its current altitude and azimuth from your location. To see when it will next be overhead:

Terminal window
curl "http://localhost:8000/api/passes/25544?days=3"

This returns upcoming passes with AOS, TCA, and LOS times, plus maximum elevation. Only passes that rise above your configured minimum elevation (default 5 degrees) are included.

Search for something

Section titled “Search for something”

The omnisearch handles more than satellite names. Try these in the command palette:

  • weather satellites — finds NOAA, GOES, Meteosat, and others
  • amateur radio UHF — finds amateur satellites with UHF downlinks
  • 25544 — finds the ISS by NORAD number
  • Jupiter — finds planets, not just satellites
  • Andromeda — deep sky objects are in there too

Check the API health

Section titled “Check the API health”
Terminal window
curl http://localhost:8000/api/health

Should return {"status": "ok", "service": "craft-api"}.

View logs

Section titled “View logs”
Terminal window
make logs

Stopping and restarting

Section titled “Stopping and restarting”
Terminal window
# Stop everything
make down


# Start again (no rebuild needed unless code changed)
make dev

Next steps

Section titled “Next steps”