Difference between revisions of "SatNOGS Client Ansible"

Latest revision as of 17:13, 12 February 2022

Introduction

Follow these instructions only if you are provisioning SatNOGS to Debian from another host or are installing on the same host.

SatNOGS Client Ansible makes the actual provisioning of the SatNOGS Client system. It is called, under the hood, when applying the configuration using SatNOGS Client Setup utility. It currently supports Raspbian and Debian (stretch and buster).

Raspbian

For Raspberry Pi, which is the reference platform for SatNOGS, a custom Raspbian image with SatNOGS Client Ansible pre-installed is available. Installation instructions are given in the Raspberry Pi Setup Guide.

Debian

These sections contain generic instructions for installing SatNOGS Client on a Debian system.

Other distributions

Other distributions are not supported by SatNOGS Client Ansible, as the pre-built packages won't be compatible. Thus, while derived from Debian, SatNOGS Client Ansible is known to break for Ubuntu and Linux Mint. If you are an experienced user, a manual installation of all components could be possible.

Installation Guide

Prerequisites

A target Debian system. To install Debian please follow the Debian Installation Guide and chose the net installer if you want to run a headless server. The target system can be the host itself.
A user (referenced later as youruser) which is member of 'sudo' group exists on the target system. Don't use the username `satnogs` when you install the Debian system.
An SSH server running on the target system.
Install installation dependencies: `sudo apt-get install ansible git sshpass python-setuptools`

Installation

On the host system run the following commands:

$ git clone https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git    # Clone SatNOGS Client Ansible repository
$ cd satnogs-client-ansible                                    # Change to cloned repository directory
$ git checkout stable                                          # Optionally, check out stable (Debian Buster 10) branch
$ cp -r production.dist production                             # Copy dist configuration
$ vi production/inventory/hosts                                # Update file with your own target host e.g. 127.0.0.1, user and SSH password
$ ssh youruser@yourtargetsystem true                           # Test SSH connection to target system
$ ansible-playbook -i production/inventory/hosts -K site.yml   # Run Ansible playbook
$ ssh -t youruser@yourtargetsystem sudo satnogs-setup          # Setup SatNOGS client (see below)

Next Steps

Follow SatNOGS Client Setup to configure your system and SatNOGS station.

@@ Line 1: / Line 1: @@
-= Intro =
+==Introduction==
-'''SatNOGS Client Ansible''' is the suggested method to install '''SatNOGS Client''' (and friends) to any Debian-based system.
+{{Warning|Follow these instructions only if you are provisioning SatNOGS to Debian from another host or are installing on the same host. }}
-= Raspbian =
+'''SatNOGS Client Ansible''' makes the actual provisioning of the '''SatNOGS Client''' system. It is called, under the hood, when applying the configuration using [[SatNOGS Client Setup|SatNOGS Client Setup utility]]. It currently supports Raspbian and Debian (stretch and buster).
-For Raspberry Pi 3, which is the reference platform for SatNOGS, a [[Raspberry_Pi_3|Raspbian image]] with '''SatNOGS Client Ansible''' pre-installed is available.
+==Raspbian==
-= Debian =
+For Raspberry Pi, which is the reference platform for SatNOGS, a custom Raspbian image with '''SatNOGS Client Ansible''' pre-installed is available. Installation instructions are given in the [[Raspberry_Pi| Raspberry Pi Setup Guide]].
-These sections contain generic instructions for installing SatNOGS Client on any Debian-based system.
+==Debian==
-== Prerequisites ==
+These sections contain generic instructions for installing SatNOGS Client on a Debian system.
-* A user which is member of 'sudo' group exists on the target system
+==Other distributions==
-* An SSH server running on the target system
-* A host system with Git and latest version of Ansible installed
-== Instructions ==
+Other distributions are not supported by '''SatNOGS Client Ansible''', as the pre-built packages won't be compatible. Thus, while derived from Debian, '''SatNOGS Client Ansible''' is known to break for Ubuntu and Linux Mint. If you are an experienced user, a manual installation of all components could be possible.
-On the host system run the following commands:
+==Installation Guide==
+===Prerequisites===
- <nowiki>
+*A target Debian system. To install Debian please follow the [https://www.debian.org/releases/stretch/installmanual Debian Installation Guide] and chose the net installer if you want to run a headless server. The target system can be the host itself.
-$ git clone https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git    # Clone SatNOGS Client Ansible repository
+*A user (referenced later as ''youruser'') which is member of 'sudo' group exists on the target system. Don't use the username `satnogs` when you install the Debian system.
-$ cd satnogs-client-ansible                              # Change to cloned repository directory
+*An SSH server running on the target system.
-$ cp -r production.dist production                       # Copy dist configuration
+*Install installation dependencies: `sudo apt-get install ansible git sshpass python-setuptools`
-$ vi production/inventory/hosts                          # Update file with your own target host, user and SSH password
-$ ssh youruser@yourtargetsystem true                     # Test SSH connection to target system
-$ ansible-playbook -i production/inventory -K site.yml   # Run Ansible playbook
-$ ssh -t youruser@yourtargetsystem sudo satnogs-setup    # Setup SatNOGS client (see below)</nowiki>
-= SatNOGS Client Setup =
+===Installation===
-<code>satnogs-setup</code> is a script for configuring a system installed with '''SatNOGS Client Ansible'''.
+On the host system run the following commands:
+  $ git clone <nowiki>https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git</nowiki>    # Clone SatNOGS Client Ansible repository
-== Initial Setup ==
+  $ cd satnogs-client-ansible                                    # Change to cloned repository directory
+  $ git checkout stable                                          # Optionally, check out stable (Debian Buster 10) branch
-Right after the first boot of the system, packages and the configuration tool itself must be updated. Follow the [[#Updating|Updating]] instruction found below.
+ $ cp -r production.dist production                             # Copy dist configuration
+ $ vi production/inventory/hosts                                # Update file with your own target host e.g. 127.0.0.1, user and SSH password
-To configure a '''SatNOGS Client Ansible''' system:
+  $ ssh youruser@yourtargetsystem true                           # Test SSH connection to target system
+ $ ansible-playbook -i production/inventory/hosts -K site.yml   # Run Ansible playbook
-# SSH into the system and run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
+  $ ssh -t youruser@yourtargetsystem sudo satnogs-setup          # Setup SatNOGS client (see below)
-# Set '''Basic Configuration''' (see below)
-# Select <code>Apply</code> and the Raspberry Pi will configure itself; this may take some time
-# Select <code>Back</code> to exit
-{{Message|You can always reconfigure the software by running <code>sudo satnogs-setup</code> again.}}
-=== Basic Configuration ===
-{| class="wikitable"
-!Setting
-!Description
-|-
-|<code>SATNOGS_API_TOKEN</code>
-|The API token assigned to your ground station on the SatNOGS Network website.
-|-
-|<code>SATNOGS_NETWORK_API_URL</code>
-|The API for the SatNOGS network site. This is <code><nowiki>https://network.satnogs.org/api/</nowiki></code>.
-|-
-|<code>SATNOGS_RX_DEVICE</code>
-|If you are using an RTL-SDR, this is <code>rtlsdr</code>.  Other devices supported by gr-satnogs include <code>usrpb200</code>, <code>usrp2</code>, <code>airspy</code> or <code>hackrf</code>; a complete list can be found [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/blob/master/apps/flowgraphs/satellites/README.md here].
-|-
-|<code>SATNOGS_STATION_ELEV</code>
-|The elevation of your ground station in metres.
-|-
-|<code>SATNOGS_STATION_ID</code>
-|The ID assigned to your station in the SatNOGS Network site.
-|-
-|<code>SATNOGS_STATION_LAT</code>
-|The latitude of your station.  North is positive, south is negative.
-|-
-|<code>SATNOGS_STATION_LON</code>
-|The longitude of your station.  East is positive, west is negative.
-|-
-|<code>HAMLIB_UTILS_ROT_ENABLED</code>
-|Whether or not to enable the Hamlibs rotator daemon.  Rotctld is a software daemon that provides a network server to control a rotator on a serial port.  If you don't have a rotator (like the [https://wiki.satnogs.org/No_rotator No rotator setup]), enter <code>False</code>.
-|-
-|<code>HAMLIB_UTILS_ROT_OPTS</code>
-|Options for rotcld. For a yaesu rotator, use <code>-m 601 -r /dev/ttyACM0 -s 9600 -T 0.0.0.0</code>
-|}
-=== Advanced Setup ===
-{| class="wikitable"
-!Setting
-!Description
-|-
-|<code>SATNOGS_CLIENT_URL</code>
-|If you to try a development version of satnogs-client, you can change the URL here.  The URL needs to be in [https://pip.pypa.io/en/stable/reference/pip_install PIP format].  Here are some examples:
-* <code><nowiki>git+https://gitlab.com/librespacefoundation/satnogs/satnogs-client.git@0</nowiki></code> -- the '0' branch (the current development version) of satnogs-client
-* <code><nowiki>git+https://gitlab.com/jdoe/satnogs-client.git@new-feature</nowiki></code> -- the 'new-feature' branch of jdoe's fork of satnogs-client
-|-
-|<code>SATNOGS_RADIO_GR_SATNOGS_PACKAGE</code>
-|This options allows you to change the installed package of gr-satnogs. For example, to install nightly development builds use:
-* <code><nowiki>https://gitlab.com/librespacefoundation/satnogs/gr-satnogs-package/-/jobs/artifacts/master/raw/build/debian/output/armhf/gr-satnogs_armhf.deb?job=nightly</nowiki></code>
-|-
-|<code>RF_GAIN</code>
-|RF Gain value for your SDR hardware. Defaults can be found [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/blob/master/python/hw_settings.py here].
-* For rtl-sdr possible values are the following: <code>0.0 0.9 1.4 2.7 3.7 7.7 8.7 12.5 14.4 15.7 16.6 19.7 20.7 22.9 25.4 28.0 29.7 32.8 33.8 36.4 37.2 38.6 40.2 42.1 43.4 43.9 44.5 48.0 49.6</code>
-|}
-{{Message|Changing these settings is ''not'' recommended unless you're developing SatNOGS.}}
-== Updating SatNOGS Client software ==
-To update all Debian packages to the latest you can use the normal APT updating methods. SSH into the system and run the following commands:
-  <nowiki>
-$ sudo apt-get update
-$ sudo apt-get -y upgrade</nowiki>
-To update SatNOGS software, incuding the configuration tool itself:
-# SSH into the system and (re-)run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
-# Select <code>Update</code> to update the configuration tool
-# Select <code>Apply</code> and the Raspberry Pi will update itself; this may take some time
-# Select <code>Back</code> to exit
-'''WARNING: An update can potentially interrupt a running observation!'''
-== Verification of correct installation ==
-To see if satnogs-client has started successfully, check the logs with journalctl:
-<pre>
-journalctl -u satnogs-client.service
-</pre>
-You should see entries running approximately once per minute that look like this:
-<pre>
-Oct 01 23:02:13 raspberrypi satnogs-client[6695]:  * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
-Oct 01 23:02:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:02:14,466 - satnogsclient - INFO - [LD] Downlink thread waiting for first downlink packet
-Oct 01 23:03:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:14,450 - apscheduler.executors.default - INFO - Running job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:03:14 UTC)" (scheduled at 2017-10-01 23:03:14.423393+00:00)
-Oct 01 23:03:47 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:47,324 - satnogsclient - DEBUG - Opening TCP socket: 127.0.0.1:5011
-Oct 01 23:03:47 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:47,325 - satnogsclient - DEBUG - Sending message: []
-Oct 01 23:03:47 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:47,327 - apscheduler.executors.default - INFO - Job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:04:14 UTC)" executed successfully
-Oct 01 23:04:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:14,453 - apscheduler.executors.default - INFO - Running job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:04:14 UTC)" (scheduled at 2017-10-01 23:04:14.423393+00:00)
-Oct 01 23:04:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:14,484 - apscheduler.executors.default - INFO - Running job "post_data (trigger: interval[0:02:00], next run at: 2017-10-01 23:04:14 UTC)" (scheduled at 2017-10-01 23:04:14.436367+00:00)
-Oct 01 23:04:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:14,489 - apscheduler.executors.default - INFO - Job "post_data (trigger: interval[0:02:00], next run at: 2017-10-01 23:04:14 UTC)" executed successfully
-Oct 01 23:04:15 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:15,627 - satnogsclient - DEBUG - Opening TCP socket: 127.0.0.1:5011
-Oct 01 23:04:15 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:15,628 - satnogsclient - DEBUG - Sending message: []
-Oct 01 23:04:15 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:15,629 - apscheduler.executors.default - INFO - Job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:05:14 UTC)" executed successfully
-</pre>
-You can also try visiting satnog-client's web interface. In your browser, go to '''<nowiki>http://(ip address of your raspberry pi):5000</nowiki>'''.  You should see something like this:
+<br />
-[[File:SatNOGS_client_screenshot.png|400px|thumb|center|SatNOGS client web page]]
+===Next Steps===
+Follow [[SatNOGS_Client_Setup|SatNOGS Client Setup]] to configure your system and SatNOGS station.
-If you see that, great -- you're ready to [[Operation|schedule your first observation]]! If not, check out the [[Troubleshooting]] page.
+[[Category:Build]]
+[[Category:Software]]