Skip to content

01. Installation

Gord Tulloch edited this page Nov 12, 2026 · 1 revision

01. Installation

This article covers installing Galileo and getting it ready to talk to your equipment: what you need, installing and starting Galileo, and then installing an INDI server or an ASCOM Alpaca bridge for the devices Galileo will control. When you are done, continue with 02. Getting Started.

Contents


What you need

Requirement Notes
An INDI server or an ASCOM Alpaca device Galileo talks to hardware only through these two protocols. It does not use Windows ASCOM/COM drivers. See Connect your equipment.
Optional: ASTAP plus a star database Needed for plate solving (the Solve screen).
Optional: PHD2 Needed for the Guiding screen.

You do not need any hardware to look around. The Star Atlas, Planning, Framing and Library screens work without a single device connected.

Which protocol is my gear using?

  • INDI: usually Linux/macOS/Raspberry Pi setups running an indiserver. You can use Astroberry (free) or Stellarmate (sold both as a cheap operating system or a hardware appliance) to create an INDI server on these platforms.
  • Alpaca: ASCOM's network protocol. Examples are devices with native Alpaca interfaces, ZWO Seestar, a Dwarf III running the dwarfAlp (https://github.com/acocalypso/dwarfAlp) Alpaca Bridge, ASCOM Remote, or the ASCOM simulators.

You can mix INDI and Alpaca devices freely within one setup.

Install Galileo

There are two ways to install, and you only need one:

Option Best for Updates
Prebuilt installer — one download per platform Most users. Nothing else to install: no Python, no Git. Download the new installer from the Releases page and run it over the old one.
Install from source — a small script that clones the repo Developers, testers following main, or platforms with no prebuilt installer. Automatic: checks for updates on every launch.

Prebuilt installers (recommended)

Download the file for your system from the Releases page:

System File How to install
Windows 10/11 (64-bit) Galileo-Setup-<version>-win-x64.exe Double-click and follow the wizard. Installs to Program Files (or your user folder if you decline admin rights) and offers a desktop shortcut.
macOS, Apple Silicon (M1 and later) Galileo-<version>-macos-arm64.dmg Open the disk image and drag Galileo onto Applications.
macOS, Intel No installer (GitHub retired the Intel build runners) Use the install-from-source script instead.
Linux, 64-bit Intel/AMD Galileo-<version>-linux-x86_64.AppImage chmod +x Galileo-*.AppImage, then double-click it or run ./Galileo-*.AppImage.
Raspberry Pi 5 (and other 64-bit ARM Linux) Galileo-<version>-linux-aarch64.AppImage Same as the x86_64 AppImage. Needs a 64-bit OS such as Raspberry Pi OS Bookworm 64-bit.

Notes:

  • macOS security prompt. Until the builds are notarized with an Apple Developer ID, macOS may say the app "cannot be opened because the developer cannot be verified". Right-click (or Control-click) Galileo in Applications, choose Open, then confirm. You only need to do this once.
  • Windows SmartScreen. The installer is not code-signed yet, so Windows may show "Windows protected your PC". Choose More info, then Run anyway.
  • Linux AppImage. If it won't start, your system may lack FUSE 2: install it with sudo apt install libfuse2 (Debian/Ubuntu), or run the AppImage with --appimage-extract-and-run.
  • Your data is kept separately. Settings, logs and the image library database live in your user folders (see Where Galileo keeps its files), so upgrading or uninstalling never touches them.
  • Uninstall. Windows: Settings > Apps. macOS: drag Galileo to the Trash. Linux: delete the AppImage.
  • Plugins are not bundled; install them from the in-app Plugin Marketplace.

Install from source (auto-updating)

These scripts clone Galileo into your home folder, set up a Python virtual environment and keep it up to date on every launch.

Windows: one-file installer

Right click on this link and select Save Link As... to download Install-Galileo-Windows.bat and double-click it. That's the only file you need — it downloads the real installer (install/install.ps1) from GitHub and runs it for you. It doesn't matter where you download it to as long as you can find it to click on it.

The installer finds (or installs) Git and Python 3.11, clones Galileo into %USERPROFILE%\Galileo, creates the virtual environment, installs dependencies, and adds a Galileo shortcut to your Desktop — no admin rights needed. It's a source-checkout installer, not a bundled executable, and updating later needs no re-download: the desktop shortcut checks for updates (git-based) every time you start Galileo from it, pulling in the latest version automatically before the app opens. See install/README.md for exactly how that works, and how to update without starting the app (install/upgrade.ps1).

To install somewhere other than the default folder, download and run install/install.ps1 directly instead of the .bat:

irm https://raw.githubusercontent.com/gordtulloch/Galileo/main/install/install.ps1 -OutFile install.ps1
.\install.ps1 -InstallDir D:\Galileo
.\install.ps1 -InstallDir D:\Galileo

macOS: one-file installer

Open Terminal and run:

curl -fsSL https://raw.githubusercontent.com/gordtulloch/Galileo/main/Install-Galileo-MacOS.sh -o Install-Galileo-MacOS.sh
chmod +x Install-Galileo-MacOS.sh
./Install-Galileo-MacOS.sh

That single script downloads the real installer (install/install.sh) from GitHub and runs it. It will offer to install Xcode Command Line Tools (if missing, provides git and compilers), then Homebrew and Python 3.11 if they are not already present. It clones Galileo into ~/Galileo, creates the virtual environment, installs dependencies, and adds a Galileo.app bundle to your Desktop — double-click it to start Galileo from that point on. The app bundle checks for updates (git-based) on every launch, so you are always on the latest version automatically. See install/README.md for exactly how that works, and how to update without starting the app (install/upgrade.sh).

To install somewhere other than the default folder, pass --install-dir:

./Install-Galileo-MacOS.sh --install-dir /opt/Galileo

Linux (Debian / Ubuntu): one-file installer

Open a terminal and run:

curl -fsSL https://raw.githubusercontent.com/gordtulloch/Galileo/main/Install-Galileo-Linux.sh -o Install-Galileo-Linux.sh
chmod +x Install-Galileo-Linux.sh
./Install-Galileo-Linux.sh

The script will use apt to install any missing system packages. It detects your exact distro from /etc/os-release and resolves Python 3.11 automatically using the best available method:

Situation What the installer does
Python 3.11+ already in apt (Ubuntu 23.04+, Raspberry Pi OS Bookworm, Debian 12) apt-get install python3.11
Ubuntu family without 3.11 in apt — Ubuntu 20.04/22.04, Stellarmate, Linux Mint, Pop!_OS … Adds the deadsnakes PPA and installs via apt
Raspberry Pi OS Bullseye or other old Debian release Warns you to upgrade to Bookworm, or offers to build Python 3.11 from source via pyenv (~5 min on RPi 5, ~15 min on RPi 4)
Any other distro where apt can't supply 3.11 Builds from source via pyenv

It then clones Galileo into ~/Galileo, creates the virtual environment, installs Python dependencies, and writes a Galileo.desktop file to your Desktop and to ~/.local/share/applications (so it appears in your app menu). The launcher checks for updates (git-based) on every start. See install/README.md for details, and how to update without launching the app (install/upgrade-linux.sh).

To install somewhere other than the default folder, pass --install-dir:

./Install-Galileo-Linux.sh --install-dir /opt/Galileo

sudo required for apt packages only. The installer calls sudo apt-get solely to install missing system packages. The virtualenv and all Python dependencies are installed in your home directory without elevated privileges.

Manual install (all platforms)

Open a terminal (PowerShell on Windows) and run:

git clone https://github.com/gordtulloch/Galileo.git
cd Galileo
python -m venv .venv

Install the dependencies into the virtual environment:

# Windows
.venv\Scripts\pip install -r requirements.txt

# macOS / Linux
.venv/bin/pip install -r requirements.txt

The first install downloads a fair number of scientific packages (numpy, astropy, scipy, PySide6 and others), so allow a few minutes.

On MacOS and Linux run chmod 700 run.sh to set the program as executable or you'll get Permission denied errors.

Developers: pip install -r requirements-dev.txt adds pytest, ruff and mypy. See CONTRIBUTING.md for the development setup.

Start Galileo

The launch scripts find the project's .venv automatically and start the app maximized.

Platform Command (run from the repository folder)
Windows PowerShell .\run.ps1
macOS / Linux, or Git Bash on Windows ./run.sh
Any platform, without the scripts .venv/bin/python -m galileo.app (Windows: .venv\Scripts\python -m galileo.app)

A splash screen shows while Galileo starts, with a progress bar and the list of operations being run (database, plugins, each screen), then the main window opens. The database is created automatically on first launch, so there is nothing to configure beforehand.

Windows PowerShell blocked the script? Run powershell -ExecutionPolicy Bypass -File .\run.ps1 once, or use the python -m galileo.app form above.

Windows, macOS and Linux (Debian/Ubuntu) all have one-file installers above whose desktop shortcuts/launchers start Galileo directly (and check for updates first). Other Linux distributions can use the manual steps below.

Installing INDI and an ASCOM Alpaca Bridge

Galileo talks to hardware through two protocols: INDI and ASCOM Alpaca. It does not use Windows ASCOM/COM drivers directly. You can mix INDI and Alpaca devices freely within one Galileo Pier.

  • INDI — covered first: installing an INDI server on macOS, Linux, Raspberry Pi, and what to do on Windows.
  • ASCOM Alpaca — covered second: when to use it instead of INDI, and bridging Windows-only ASCOM/COM drivers onto the network with ASCOM Remote.

Installing INDI on macOS

To install INDI on macOS, the most common method is using Homebrew. Open your Terminal and run the following commands to tap the INDI repository and install the binaries:

brew tap indilib/indi
brew install indi-bin

Alternatively, you can install INDI via MacPorts by running sudo port install indi after installing MacPorts. For a standalone server GUI without compiling, you can download pre-built distributions like INDIWebManagerApp or INDIStarter from their respective GitHub or SourceForge pages, which bundle the server and drivers into a native macOS application. If you prefer building from source, you can clone the indi repository and use cmake to compile it, or use community scripts like indi-mac or kstars-on-osx-craft to build the server and drivers using Craft.

Installing INDI on Linux

If you'd rather not assemble the stack yourself, the easiest route on a Linux MiniPC is the same prebuilt image used on Raspberry Pi:

  • Stellarmate X (www.stellarmate.com) — a commercial small-form-factor MiniPC appliance preloaded with Stellarmate OS (INDI, INDI Web Manager, and KStars/Ekos preinstalled).
  • Astroberry Server — a free, community-maintained image with the same INDI + INDI Web Manager + KStars/Ekos stack, available at astroberry.io. Astroberry originated as a Raspberry Pi image (see the Raspberry Pi section below) but also runs fine on generic x86 MiniPC hardware.

See the Raspberry Pi section below for more on both — they're the same images either way, just running on x86 instead of ARM.

If you'd rather install onto an existing Linux install (desktop distro or a MiniPC you're setting up yourself), the INDI project maintains an official PPA for Debian/Ubuntu-based distributions:

sudo add-apt-repository ppa:mutlaqja/ppa
sudo apt-get update
sudo apt-get install indi-full gsc

indi-full pulls in the complete set of third-party device drivers along with the core indiserver binary; if you only need a handful of drivers you can install individual packages instead (e.g. indi-eqmod, indi-asi, indi-gphoto) to save space on constrained devices. For other distributions (Fedora, Arch, openSUSE), check the INDI download page for distro-specific packages, or build from source with cmake as described above for macOS — the INDI core and third-party driver repositories (indi-3rdparty) build the same way on any Linux target.

Once installed, run the server directly for a specific driver set:

indiserver -v indi_eqmod_telescope indi_asi_ccd

For day-to-day use, install INDI Web Manager (sudo apt-get install indiwebmanager or pip install indiweb) instead of starting indiserver by hand — it runs as a service, and lets you save/start/stop driver profiles from a web UI on port 8624. This is exactly what Stellarmate X and Astroberry run under the hood.

Installing INDI on Raspberry Pi

The two easiest ways to get INDI up and running on Raspberry Pi:

  • Stellarmate OS (www.stellarmate.com) — a commercial, prebuilt Raspberry Pi OS image with INDI, INDI Web Manager, and KStars/Ekos preinstalled. If you'd rather not manage a bare Pi, the same image ships preloaded on Stellarmate's "Stellarmate X" MiniPC appliances — see the Linux section above.
  • Astroberry Server — a free, community-maintained image with the same INDI + INDI Web Manager + KStars/Ekos stack, available at astroberry.io. This is its native platform — it originated as a Raspberry Pi project, and also runs fine on x86 MiniPC hardware (see the Linux section above).

Alternatively you can flash Raspberry Pi OS Lite yourself and follow the Linux apt instructions above — this gives the smallest footprint and is the recommended path for a headless, minimal INDI server dedicated to a single Pier. Harald's astrophotography site also hosts minimal pre-built INDI-only images for various Pi models:

https://sites.google.com/view/haraldsastrophotography/software/hotspot-based-images?pli=1&authuser=0

Whichever route you choose, point Galileo's device connection dialog at the Pi's IP address on port 7624 (the INDI default) once indiserver or INDI Web Manager is running.

Installing INDI on Windows

Currently there is no version of INDI for Windows. We suggest running a Raspberry Pi (or any Linux box) with INDI on your telescope to provide INDI access to your directly-connected hardware — see "Installing INDI on Linux" or "Installing INDI on Raspberry Pi" above. Galileo then connects to that INDI server over the network from Windows exactly as it would from any other platform.

If your equipment only has Windows ASCOM/COM drivers and no INDI driver exists for it, don't run INDI at all — instead bridge those drivers onto the network as Alpaca devices. See Installing an ASCOM Alpaca bridge below.

When to use Alpaca instead of INDI

Use Alpaca when:

  • Your device already ships a native Alpaca driver or firmware (e.g. a ZWO Seestar's built-in Alpaca server, ASCOM Platform 7 drivers, or a growing number of Alpaca-native devices). In that case there's nothing to bridge — just point Galileo at the device's IP and port directly.
  • Your device only has a traditional Windows ASCOM/COM driver, and you want Galileo — potentially running on a different machine, or on macOS/Linux where COM doesn't exist at all — to reach it over the network. This requires a bridge that exposes the COM driver as an Alpaca endpoint, covered below.

You can mix INDI and Alpaca devices freely within one Galileo Pier.

Installing the bridge

If your mount, camera, focuser, or other device only ships a Windows ASCOM/COM driver, you can expose it to Galileo (and any other Alpaca client) over the network using ASCOM Remote, the official bridge maintained by the ASCOM Initiative. It runs on the same Windows PC as your COM drivers and translates Alpaca HTTP requests into COM calls behind the scenes — Galileo itself never needs to know COM exists.

1. Prerequisites

  1. Install the ASCOM Platform. Download the latest installer from ascom-standards.org/Downloads and run it. This installs the COM infrastructure that both your device drivers and ASCOM Remote depend on.
  2. Install your device's native ASCOM/COM driver from the manufacturer (mount, camera, focuser, filter wheel, etc.) and confirm it connects correctly using the vendor's own tool or the ASCOM Device Hub/Diagnostics utility that ships with the Platform. Get this working locally before adding the network bridge — it rules out driver problems before you start debugging the bridge.

2. Install ASCOM Remote

  1. From the same ASCOM downloads page, download ASCOM Remote (listed under "Remote / Alpaca" tools; it may also be offered as an optional component in the main Platform installer, depending on version).
  2. Run the installer. It adds an ASCOM Remote Server application plus a small system-tray configuration UI.
  3. Launch ASCOM Remote Server from the Start menu. The first run opens its configuration page in your browser (it's a local web UI, typically at http://localhost:32323/setup).

3. Configure the bridge

In the ASCOM Remote configuration page:

  1. Under Setup → Device Configuration, add a new device entry for each COM driver you want to expose (mount, camera, focuser, etc.). Pick the installed ASCOM driver from the dropdown for each.
  2. Each device is assigned an Alpaca device type and device number (e.g. Telescope #0, Camera #0) — note these down, since Galileo's device picker will show them the same way.
  3. Under Setup → Server Configuration, confirm the IP address and port (default 32323) ASCOM Remote listens on. If this PC has multiple network adapters, bind to the one reachable from wherever Galileo runs (or 0.0.0.0/all adapters if you're unsure).
  4. If Windows Firewall prompts you when the server first starts, allow access on Private networks (or add a manual inbound rule for TCP port 32323) — otherwise devices on your LAN, including Galileo running on another machine, won't be able to reach it.
  5. Start (or restart) the ASCOM Remote Server so it begins listening.

4. Verify the bridge before connecting Galileo

Alpaca devices support discovery and a plain HTTP management API, so you can sanity-check the bridge without Galileo:

  • Open http://<bridge-pc-ip>:32323/setup from a browser on another machine on the same network — you should see the same configuration page.
  • Open http://<bridge-pc-ip>:32323/management/apiversions — this should return a small JSON document, confirming the Alpaca API is responding over the network (not just on localhost).

5. Connect from Galileo

In Galileo's device connection dialog, choose Alpaca as the driver, enter the bridge PC's IP address, and set the port to 32323 (or whatever you configured in step 3). Scan for devices — the mount, camera, or other equipment you added in ASCOM Remote should appear using the same device numbers you noted earlier. This works whether Galileo is running on the same Windows PC as the bridge, or remotely from macOS, Linux, or a Raspberry Pi elsewhere on the network — the whole point of the bridge is that COM never has to leave the Windows box, only Alpaca traffic does.

6. Notes and troubleshooting

  • ASCOM Remote vs. Alpaca simulators: don't confuse ASCOM Remote (the bridge for real COM drivers, above) with the ASCOM Alpaca Simulators package, which only exposes simulated devices for testing. If you just want to test Galileo's Alpaca support without hardware, the simulators are a faster path — the Getting Started mentions them running on port 11111 by default.
  • One bridge PC can serve many devices. You don't need a separate instance of ASCOM Remote per device — add every COM driver on that machine to the one running server, each with its own device number.
  • Port already in use: if 32323 conflicts with something else (e.g. a Seestar's own built-in Alpaca server also defaulting to that port), change ASCOM Remote's listening port in Server Configuration and use the new port when connecting from Galileo.
  • Discovery finds nothing: Alpaca's UDP auto-discovery only works within the same broadcast domain (same LAN segment/VLAN). Across subnets, VPNs, or Wi-Fi isolation-enabled routers, enter the bridge PC's IP address and port directly in Galileo instead of relying on scan/discovery.
  • Nothing responds at all: check that ASCOM Remote Server is actually running (not just installed), that the underlying COM driver still connects locally, and that Windows Firewall isn't silently blocking the port — the /management/apiversions check in step 4 isolates network/firewall problems from driver problems.

Clone this wiki locally