Manual installation
This page walks through everything Install via script does for you automatically, one piece at a time, so you can make your own choice at each step instead. It assumes you are comfortable on a Linux command line.
Ubuntu 24.04 LTS “Noble” and 26.04 LTS “Resolute” (amd64), Ubuntu 26.04 arm64 (Raspberry Pi), Fedora (amd64), Arch Linux (amd64). Nothing below has been tested outside these.
1. Choose your source
| System | Sources |
|---|---|
| Ubuntu 24.04 (Noble), amd64 | GitLab only |
| Ubuntu 26.04 (Resolute), amd64 | GitLab, or the Launchpad PPA |
| Ubuntu 26.04 (Resolute), arm64 (Raspberry Pi) | Launchpad PPA only - GitLab does not publish an arm64 build |
| Fedora, amd64 | GitLab only |
| Arch Linux, amd64 | GitLab only |
GitLab gives you a specific .deb/.rpm/.pkg.tar.zst file you download and install by hand - full control over exactly which version runs, updates are a manual re-download. Two packages: ostserver (backend only) or ostserver-complete (backend + web UI + nginx wiring, Conflicts/Replaces ostserver - never install both). File names follow <package>_<channel>_<suffix>:
| System | Suffix |
|---|---|
| Ubuntu 24.04 | 2404_amd64.deb |
| Ubuntu 26.04 | 2604_amd64.deb |
| Fedora | fc_x86_64.rpm |
| Arch | arch_x86_64.pkg.tar.zst |
channel is latest (rolling) or a specific released version tag. The download URL is always:
https://gitlab.ostserver.fr/api/v4/projects/1/packages/generic/<channel>/<channel>/<package>_<channel>_<suffix>The GitLab registry also publishes a nightly channel - development builds from arbitrary feature branches, CI-only, never meant for an end-user machine. Stick to latest or a real version tag.
Launchpad PPA (Ubuntu only) installs via apt and updates automatically with apt upgrade - less control over the exact version, but no manual re-download ever needed. Two channels: ppa:gehelem/ostserver (stable) or ppa:gehelem/ostserver-daily (rolling, built from main’s HEAD).
The rest of this page shows both paths where they differ.
2. Install INDI
INDI is the hardware abstraction layer driving cameras, mounts, focusers and filter wheels. ostserver depends on it.
Ubuntu
sudo add-apt-repository -y ppa:mutlaqja/ppa
sudo add-apt-repository -y universe
sudo apt update
sudo apt install -y libindi1 indi-binostserver’s own package dependencies only ever cover libindi1 - dpkg auto-detects it from the binary actually linking against it (shlibs:Depends). indiserver itself (the process that actually runs the drivers, provided by indi-bin) is never linked against, only exec’d as a subprocess - nothing pulls it in automatically. Skip this and the embedded INDI server has nothing to start. Caught live: a fresh install with ostserver’s own dependencies alone had no indiserver binary at all.
Fedora
sudo dnf install -y libindiThe RPM’s own auto-detected Requires does not reliably pull libindi in either - install it explicitly, same reasoning as indi-bin above.
Arch Linux
Nothing to do here - libindi is in the official [extra] repository, and it is a hard depends of the ostserver/ostserver-complete AUR packages themselves, so installing the package in step 4 pulls it in automatically.
3. Install third-party INDI drivers
Most real cameras, mounts and filter wheels (ZWO, QHY, PlayerOne and others) need a driver from here - skip this section if you only use the built-in simulators.
Ubuntu
sudo apt install -y indi-3rdparty-libs indi-3rdparty-driversArch Linux
No official package (pacman or AUR) bundles every third-party driver in one. indi-3rdparty-drivers (AUR, maintainer astromatto) builds straight from the same official indilib/indi-3rdparty source tarball the Debian/Fedora packages use, covering the same vendors - but it depends on a second AUR-only package, indi-3rdparty-libs, that pacman cannot resolve by itself without an AUR helper. Build and install both, in this order:
sudo pacman -S --needed base-devel git
for pkg in indi-3rdparty-libs indi-3rdparty-drivers; do
git clone "https://aur.archlinux.org/${pkg}.git"
(cd "${pkg}" && makepkg -si)
rm -rf "${pkg}"
doneExpect pages of compiler output and several minutes per package - normal for an AUR build, not a sign something is wrong.
Fedora
No official or RPM Fusion package exists for this either. xsnrg/indi-3rdparty-bleeding (COPR, same maintainer as xsnrg/libindi and xsnrg/kstars) builds one RPM per driver, covering the same vendors.
sudo dnf copr enable -y xsnrg/indi-3rdparty-bleeding
sudo dnf install -y 'indi-*'This is not an official Fedora or RPM Fusion repository. It also has no stable/tagged counterpart (unlike xsnrg/libindi/xsnrg/kstars, which both do) - only this git-tracking “bleeding” build, closer in spirit to a nightly channel than a release. Decide for yourself whether that is an acceptable tradeoff for your setup.
4. Install the OST package
From GitLab
PKG=ostserver-complete # or: ostserver (backend only)
CHANNEL=latest # or: a specific version tag
SUFFIX=2604_amd64.deb # see the table in step 1 for your system
FILE="${PKG}_${CHANNEL}_${SUFFIX}"
wget "https://gitlab.ostserver.fr/api/v4/projects/1/packages/generic/${CHANNEL}/${CHANNEL}/${FILE}"Then install the downloaded file:
sudo apt install -y "./${FILE}" # Ubuntu
sudo dnf install -y "./${FILE}" # Fedora
sudo pacman -U "./${FILE}" # ArchFrom the Launchpad PPA (Ubuntu only)
sudo add-apt-repository -y ppa:gehelem/ostserver # or ppa:gehelem/ostserver-daily
sudo apt update
sudo apt install -y ostserver-complete # or: ostserverEither way, the package installs:
/usr/bin/ostserver- the main binary/usr/lib/libost*.so- the modules (focus, guider, sequencer, navigator, planner, polar, inspector, indipanel, allsky…)- with
ostserver-complete: the web UI’s static files, and (Debian/Ubuntu only - see step 8) an nginx site already wired to serve them /usr/lib/systemd/system/ostserver.service- see step 9 before touching it
5. Astrometry.net and index files
Required for plate solving (Navigator and Polar modules).
Package
sudo apt install -y astrometry.net # Ubuntu
sudo dnf install -y --setopt=install_weak_deps=False astrometry # FedoraFedora’s astrometry RPM has a weak dependency on astrometry-data-4107-4119 - a different, older index series than the one installed below, pure wasted bandwidth and disk space alongside it. --setopt=install_weak_deps=False skips it.
Arch has no official package - build from AUR:
sudo pacman -S --needed libnewt base-devel git
git clone https://aur.archlinux.org/astrometry.net.git
(cd astrometry.net && makepkg -si)
rm -rf astrometry.netIndex files
Not distributed as a package on any distro - download directly from data.astrometry.net. Start with the wide-field base set (~152 MB total):
sudo mkdir -p /usr/share/astrometry
for idx in 4208 4209 4210 4211 4212 4213 4214; do
sudo wget -nc -P /usr/share/astrometry "http://data.astrometry.net/4200/index-${idx}.fits"
doneAdd narrower-field indexes as needed for long focal lengths - each one is several hundred MB to several GB, split into tiles:
| Index | Field of view | Size | Tiles |
|---|---|---|---|
| 4207 | 22’-30' | ~158 MB | 00-11 |
| 4206 | 16’-22' | ~313 MB | 00-11 |
| 4205 | 11’-16' | ~629 MB | 00-11 |
| 4204 | 8’-11' | ~1.2 GB | 00-47 |
| 4203 | 5.6’-8' | ~2.5 GB | 00-47 |
| 4202 | 4’-5.6' | ~4.7 GB | 00-47 |
| 4201 | 2.8’-4' | ~8.6 GB | 00-47 |
| 4200 | 2’-2.8' | ~13.2 GB | 00-47 |
IDX=4207 # pick one from the table
LAST=11 # 11 for 4205-4207, 47 for 4200-4204
for i in $(seq -w 0 "${LAST}"); do
sudo wget -nc -P /usr/share/astrometry "http://data.astrometry.net/4200/index-${IDX}-${i}.fits"
done-nc (no-clobber) skips a file already downloaded - safe to re-run to top up a partial set.
6. gsc (optional)
Guide Star Catalog - realistic star field data for INDI’s CCD simulator only, never needed for real hardware.
sudo apt install -y gsc # Ubuntu, regular apt packageArch and Fedora have no official package that builds under modern toolchains - a prebuilt package of our own instead:
GSC=gsc_arch_x86_64.pkg.tar.zst # Arch
# GSC=gsc_fc_x86_64.rpm # Fedora
wget "https://gitlab.ostserver.fr/api/v4/projects/1/packages/generic/gsc/1.2/${GSC}"
sudo pacman -U "./${GSC}" # Arch
# sudo dnf install -y "./${GSC}" # Fedora7. Documentation (optional)
The site you are reading right now, servable locally alongside the web UI:
CHANNEL=latest # matches the channel you installed ostserver from
DOC="documentation_${CHANNEL}.tar.gz"
wget "https://gitlab.ostserver.fr/api/v4/projects/1/packages/generic/${CHANNEL}/${CHANNEL}/${DOC}"
sudo mkdir -p /var/www/pilost/documentation
sudo tar -xzf "${DOC}" -C /var/www/pilost/documentationSee step 8 for how it needs to be served (subpath link rewriting).
8. Web server
ostserver-complete needs a web server for four things:
- Serve the front end and media files - static files plus
/ostmedia/aliased to/var/lib/osterix/media/. - Serve the documentation under
/documentation/- the Hugo theme used here emits root-relative links (href=/...,src=/..., twodata-*attributes and one inline JS variable), so without rewriting them to/documentation/...they resolve to the domain root instead. - Proxy and cache the HiPS sky-survey tiles the Navigator module’s planetarium view fetches from
alasky.cds.unistra.fr- an on-demand cache (not a full offline mirror, the real survey is several TB), so a tile is fetched from the CDS once and served locally to every client after that. - Optionally, proxy the WebSocket with TLS termination - if you want HTTPS/WSS handled by the web server instead of
ostserver’s own--ssl=Y/--sslcert/--sslkeyoptions.
nginx is what the Debian/Ubuntu package wires up for you automatically (goals 1-3; goal 4 is not currently generated anywhere, you would add it yourself the same way on any web server). Nothing stops you from using something else instead - here is what each option actually gets you.
nginx (what the package already does)
On Debian/Ubuntu, ostserver-complete’s own postinst does all of this for you - nothing to do here, skip straight to customizing it. On Arch and Fedora, packaging deliberately never touches nginx or the service (both distros’ own “hands-off” convention) - wire it up yourself:
sudo pacman -S --needed nginx # Arch
# sudo dnf install -y nginx # Fedora
sudo systemctl enable --now ostserver.service
# Make sure nginx.conf actually includes conf.d/*.conf at the http{}
# level - already the case on Fedora, not guaranteed on a fresh Arch
# install:
grep -q 'include /etc/nginx/conf\.d/\*\.conf;' /etc/nginx/nginx.conf || \
sudo sed -i '/^http {/a\ include /etc/nginx/conf.d/*.conf;' /etc/nginx/nginx.conf
sudo mkdir -p /etc/nginx/conf.d
sudo cp /usr/share/doc/ostserver-complete/pilost.conf.example /etc/nginx/conf.d/pilost.conf
sudo systemctl enable --now nginx.service
sudo systemctl reload nginx.serviceFedora’s stock nginx.conf bundles its own default server_name _; block directly in the main file, which wins over conf.d/pilost.conf unless removed first - and SELinux/firewalld need telling too:
sudo awk '
/^[[:space:]]*server[[:space:]]*\{/ && !done { depth = 1; skip = 1; next }
skip { if ($0 ~ /\{/) depth++; if ($0 ~ /\}/) depth--; if (depth == 0) { skip = 0; done = 1 }; next }
{ print }
' /etc/nginx/nginx.conf | sudo tee /etc/nginx/nginx.conf.new >/dev/null
sudo mv /etc/nginx/nginx.conf.new /etc/nginx/nginx.conf
sudo restorecon -v /etc/nginx/nginx.conf /etc/nginx/conf.d/pilost.conf
sudo firewall-cmd --add-port=80/tcp --add-port=9624/tcp --permanent
sudo firewall-cmd --reloadUnlike the Debian/Ubuntu postinst (see below), this just copies an example once - there is no pilost-local.conf convention here. /etc/nginx/conf.d/pilost.conf is yours entirely from this point on; nothing will ever overwrite it again automatically, but nothing protects a hand edit either if you re-copy the example later.
Customizing nginx safely
On Debian/Ubuntu, /etc/nginx/sites-available/pilost is regenerated from scratch on every apt upgrade - a hand edit there is silently lost on the next one. Put your own additions in /etc/nginx/pilost-local.conf instead (included near the end of the generated site’s server {} block) - that file is created once, empty, and never touched again by the package.
Debian’s stock nginx.conf already includes conf.d/*.conf at the http{} level, the same as sites-enabled/*. A file placed in conf.d/ and included a second time from inside the generated site’s own server{} block would be parsed twice - once outside any server{} context, where a location directive is a syntax error that breaks nginx -t for the whole machine, not just this site. pilost-local.conf lives directly under /etc/nginx/ for exactly this reason.
Apache (alternative, full parity achievable)
Apache can replicate all four goals: mod_substitute for the documentation link rewriting, mod_proxy + mod_cache_disk for the HiPS cache, mod_proxy_wstunnel for the WebSocket.
# /etc/apache2/sites-available/pilost.conf
# a2enmod substitute proxy proxy_http proxy_wstunnel cache cache_disk headers rewrite
CacheRoot /var/cache/apache2/hips
CacheEnable disk /hips-proxy/dss2color/
CacheDirLevels 2
CacheDirLength 1
<VirtualHost *:80>
DocumentRoot /var/www/pilost
Alias /ostmedia/ /var/lib/osterix/media/
<Directory /var/lib/osterix/media/>
Options +Indexes
Require all granted
</Directory>
# Goal 3: HiPS tile proxy + cache
ProxyPass /hips-proxy/dss2color/ https://alasky.cds.unistra.fr/DSS/DSSColor/
ProxyPassReverse /hips-proxy/dss2color/ https://alasky.cds.unistra.fr/DSS/DSSColor/
# Goal 2: documentation under a subpath, links rewritten the same
# way nginx's sub_filter does it
Alias /documentation/ /var/www/pilost/documentation/
<Location /documentation/>
AddOutputFilterByType SUBSTITUTE text/html
Substitute "s|href=/|href=/documentation/|q"
Substitute "s|src=/|src=/documentation/|q"
Substitute "s|data-nav-id=/|data-nav-id=/documentation/|q"
Substitute "s|data-url=/|data-url=/documentation/|q"
Substitute "s|index_js_url=\"/|index_js_url=\"/documentation/|q"
</Location>
# Goal 4: WebSocket proxy, if terminating TLS here instead of
# ostserver's own --ssl=Y (only useful on an HTTPS vhost)
# ProxyPass /ws ws://127.0.0.1:9624/
</VirtualHost>lighttpd (alternative, two real gaps)
lighttpd replicates goal 1 (static files) and goal 4 (WebSocket proxy, mod_proxy supports the upgrade since 1.4.46) cleanly, but has no standard module for response-body text rewriting (goal 2) or for disk-caching proxied content (goal 3) - nothing built-in equivalent to sub_filter/mod_substitute or proxy_cache/mod_cache_disk.
# /etc/lighttpd/conf-available/10-pilost.conf
server.modules += ("mod_alias", "mod_proxy")
server.document-root = "/var/www/pilost"
alias.url += ( "/ostmedia/" => "/var/lib/osterix/media/" )
# Goal 4: WebSocket proxy
$HTTP["url"] =~ "^/ws" {
proxy.server = ( "" => ( ( "host" => "127.0.0.1", "port" => 9624 ) ) )
}Two workarounds instead of the missing modules:
- Goal 2 (documentation): sidestep the need for rewriting entirely by serving the documentation on its own vhost or port, at the domain root (
/, not/documentation/) - no subpath means no links to rewrite. - Goal 3 (HiPS): a plain reverse proxy, without caching, still works - every client’s own tile requests just go straight to the CDS each time instead of hitting a local cache, which is the only thing lost:
$HTTP["url"] =~ "^/hips-proxy/dss2color/" {
proxy.server = ( "" => ( ( "host" => "alasky.cds.unistra.fr", "port" => 443 ) ) )
}9. systemd service
sudo systemctl status ostserver.serviceIt is not a package conffile on any backend (Debian, RPM, Arch alike) - it is reinstalled verbatim on every upgrade, silently discarding any direct edit. The package’s own post-install step already writes User=/WorkingDirectory= through a drop-in instead, at /etc/systemd/system/ostserver.service.d/local.conf, which no packaging backend ever touches.
For your own customization (Restart=, extra Environment=, resource limits…), use the same mechanism rather than editing anything shipped:
sudo systemctl edit ostserver.serviceThis opens an editor for your own override, merged on top of the shipped unit (and the package’s own drop-in) at startup - upgrade-safe, zero packaging work required.
10. Configuration file
Startup options (webroot, embedded INDI server, log level, language, SSL…) live in ~/.ost/ostserver.parms, one flag per line, never overwritten on upgrade. See Managing the ostserver service for the full options reference.
11. Verify the installation
sudo systemctl status ostserver
sudo systemctl status nginx # if using it
ss -tlnp | grep -E '80|9624|7624'
sudo journalctl -u ostserver -f
sudo nginx -t # if using it12. Update
# GitLab source: re-download and reinstall (same commands as step 4,
# same channel - "latest" always points at the newest build, a
# specific version tag never changes and has nothing to update to)
sudo systemctl restart ostserver
# PPA source (Ubuntu)
sudo apt update && sudo apt upgrade -y
# Arch AUR packages (indi-3rdparty-*, astrometry.net, gsc)
# re-run the clone + makepkg -si from their own section above
# Fedora COPR drivers
sudo dnf update13. Uninstall
sudo apt remove ostserver-complete # or: dnf remove / pacman -R
sudo systemctl disable --now ostserver
sudo rm -rf /etc/systemd/system/ostserver.service.d
sudo systemctl daemon-reload/usr/share/astrometry, /var/lib/osterix/media and ~/.ost/ are left in place - remove them by hand if you want them gone too.
14. Raspberry Pi / arm64
Only reachable through the Launchpad PPA, on Ubuntu 26.04 (Resolute) - GitLab does not publish an arm64 build of any package. Everything else on this page applies the same way once the OS and INDI PPA are in place.