Docs · How it works · Camera · First night · Using the desk

Install TwilightScan

TwilightScan is free for home use: no cost and no subscription. Using it for a business, school or observatory needs a license; ask us. It runs in Docker on a computer at your house, next to the camera. Nothing is sent to us except what you put in a support ticket. It downloads satellite orbits (CelesTrak), a star catalog and the weather forecast (Open-Meteo, which is sent your latitude and longitude) from public services.

What you need

• An IP camera with RTSP on your network, pointed at the sky. Amcrest, Reolink and Hikvision are built in; any other camera works with its RTSP address. Camera settings.
• A Linux computer or VM that stays on all night, with Docker. The image is linux/amd64 (Intel or AMD, not ARM or Raspberry Pi).
• 8 GB of RAM and 6 or more CPU cores.
• Disk: about 30 GB a night at 6 Mbps. Raw recordings are kept 7 days by default, so plan on 250 GB or more.
• The clock set by NTP. Timestamps are how it matches stars and satellites.

1. Settings file

Everything TwilightScan keeps lives in one data folder, /srv/twilightscan below. Start the settings file from the copy inside the image:

sudo mkdir -p /srv/twilightscan
docker run --rm --entrypoint cat ghcr.io/pastforwardgames/twilightscan site.example.json   | sudo tee /srv/twilightscan/site.json >/dev/null
sudo nano /srv/twilightscan/site.json

It looks like this. Change every value: the location and camera are placeholders.

{
  "latitude": 39.83,
  "longitude": -98.58,
  "timezone": "America/Chicago",
  "camera": {
    "ip": "192.0.2.10",
    "user": "admin",
    "password": "change-me",
    "brand": "Amcrest"
  },
  "maskBottom": 0.28,
  "nightStart": 20,
  "nightEnd": 6,
  "storage": {
    "keepRawDays": 7,
    "minFreeGb": 60
  },
  "community": "https://twilightscan.com"
}

brand is Amcrest, Reolink or Hikvision. For any other camera, leave brand out and put "rtsp": "rtsp://user:password@address:554/..." inside camera, using the camera's own stream address. The camera's address, user and password are only ever read from this file; the review desk can't change them. The container stops with "no site.json" until the file exists.

2. Start it

Save this as docker-compose.yml. Change TZ to the site's time zone, and put every name or address you open the page by in TWILIGHTSCAN_TLS_NAMES (space-separated).

services:
  twilightscan:
    image: ghcr.io/pastforwardgames/twilightscan:latest
    container_name: twilightscan
    restart: unless-stopped
    stop_grace_period: 30s
    security_opt:
      - no-new-privileges:true
    mem_limit: 2560m
    ports:
      - "8443:8443"
      - "8765:8765"
    environment:
      TZ: America/Chicago
      TWILIGHTSCAN_TLS_NAMES: "twilightscan.local"
    volumes:
      - /srv/twilightscan:/data

docker compose up -d
docker logs -f twilightscan

The log line "TwilightScan data /data review desk ..." means it is running. The container runs as uid 1000 and takes ownership of the data folder on first start. docker stop closes the current recording segment. Update with docker compose pull && docker compose up -d.

3. Set the password right away

Open https://<host>:8443 (port 8765 only redirects). Whoever opens the desk first sets its password, so do it before anyone else on your network can. The username field is only there so a password manager can save the login. The page uses the box's own certificate: accept the warning once, or install it from Settings, Security.

4. You're done when

Nothing records in daylight. Recording starts 15 minutes before civil dusk and stops 15 minutes after civil dawn, in 10-minute segments. The next morning, the inbox lists what moved. Then follow the first night.

Proxmox

Without Docker

TwilightScan is Python and ffmpeg, and runs as a Linux service or on Windows from the source. The source isn't public yet, so Docker is the way to install it today.

Recordings on a NAS

Mount the share on the host, then set "library" in site.json to that path. In Docker, mount the share into the container and use the container path, for example /archive. If the share is missing when a night starts, TwilightScan records to <root>/library instead and logs it.

Getting help

Help on the desk files a ticket here, with no account needed. To follow the reply on this site, make an account with the same email. To point a desk at a different copy of this site, set community in site.json or the TWILIGHTSCAN_COMMUNITY environment variable. The default is https://twilightscan.com.