Skip to content

Installation

Jump to bottom
W9KSB edited this page Jun 14, 2026 · 2 revisions

Installation

Overview

Pi-Sat installs as a systemd-managed service on the Raspberry Pi. The recommended install path is the one-line installer. A manual install path is also supported if you want to go that route as well.

Related pages:

Recommended Quick Install

Run this on the Pi as the normal user:

curl -fsSL https://raw.githubusercontent.com/W9KSB/Pi-Sat/main/install/install_pi.sh | sh

What the Installer Does

The installer performs the following steps:

  1. clones or updates the repository into ~/pi-sat
  2. creates pi-sat-controller.conf from the example template if needed
  3. creates update_pi.sh from updater.template if needed
  4. creates a Python virtual environment in .venv
  5. installs Python dependencies from requirements.txt
  6. installs or updates the pi-sat systemd service
  7. starts the service

Resulting Pi Layout

After install, the expected layout is:

~/pi-sat/
  frontend/
  install/
  pi_sat_controller/
  systemd/
  .venv/
  pi-sat-controller.conf
  update_pi.sh

Manual Install

If you prefer to clone and install manually:

git clone https://github.com/W9KSB/Pi-Sat.git ~/pi-sat
cd ~/pi-sat
sh install/install_pi.sh

First Configuration Steps

After installation:

  1. edit ~/pi-sat/pi-sat-controller.conf if needed
  2. set your station location and elevation
  3. configure RX, TX, SDR, and rotator settings as needed
  4. configure automation scripts if you plan to use AOS or LOS actions
  5. restart the service if you changed settings outside the UI

First Run Checklist

After the service starts for the first time:

  1. open the web UI in the browser
  2. confirm the dashboard loads without stale assets or missing sections
  3. verify station location is correct
  4. force-update TLE data and confirm passes appear
  5. add the satellites you actually want to track
  6. verify frequency profiles load for at least one satellite
  7. use the settings-page Test RX button first
  8. use the settings-page Test TX button second if used
  9. use the settings-page Test Rotator button last if used
  10. test automation scripts from the settings page if you plan to use AOS or LOS actions

If you are building up a full station, validate one device path at a time instead of trying to bring up SDR, radio, and rotator control all at once. This makes it easier to identify and isolate any issues if you encounter them.

Service Management

Useful service commands:

sudo systemctl status pi-sat
sudo systemctl restart pi-sat
journalctl -u pi-sat -f

How the Service Is Installed

Pi-Sat installs a systemd unit that:

  • starts after the network is up
  • runs the backend from the local virtual environment
  • restarts on failure
  • can bind to port 80

Updating After Install

The installer creates a local updater script:

cd ~/pi-sat
sh update_pi.sh

That updater stops the service, updates the Git checkout, refreshes Python dependencies, and restarts the service.

If You Prefer the Fully Manual Update Flow

cd ~/pi-sat
sudo systemctl stop pi-sat
git fetch --all --prune
git pull --ff-only
. .venv/bin/activate
python -m pip install -r requirements.txt
sudo systemctl start pi-sat

Notes

  • pi-sat-controller.conf is local-only and should be preserved per Pi
  • update_pi.sh is generated locally and should be preserved per Pi
  • both are intentionally excluded from normal Git updates - the goal is to make sure we are able to update the software without overwriting your config forcing you to rebuild that portion every time an update is released.

Clone this wiki locally