Installation#

Gecko runs on Linux with Python 3.8 or newer. These steps are for the person setting up an instrument machine. Operators only need the operator guide.

System requirements#

Needed for	Requirement
Everything	Python ≥ 3.8 and `pip` (or `pipx`)
Everything	Read access to the instrument’s log and science directories
Screenshots	`xwd` and ImageMagick `convert` on `PATH`, plus access to the X11 displays
Email alerts	A working `sendmail` at `/usr/sbin/sendmail` (Postfix and Sendmail both provide one)

Screenshots and email are optional. Without them, Gecko still builds the report and prints a message about the step that couldn’t run.

Install the screenshot tools with your distribution’s package manager. Package names vary by release. xwd usually comes from x11-apps on Debian/Ubuntu, and from xorg-x11-apps or xwd on RHEL, Rocky and Alma. ImageMagick is imagemagick on Debian/Ubuntu and ImageMagick on RHEL-family systems (from EPEL on some releases). Check that they’re available:

$ command -v xwd convert

Install Gecko#

Pick one of these. Each one gives you a gecko command.

Option A: shared virtual environment (recommended for instrument machines)#

$ sudo python3 -m venv /opt/gecko
$ sudo /opt/gecko/bin/pip install "git+https://github.com/CaltechOpticalObservatories/gecko.git"
$ sudo ln -s /opt/gecko/bin/gecko /usr/local/bin/gecko

To upgrade later, rerun the pip install line with --upgrade.

Option B: per-user install with pipx#

$ pipx install "git+https://github.com/CaltechOpticalObservatories/gecko.git"

Option C: source checkout#

Use this if you want to run straight from a clone, as with releases before 0.2:

$ git clone https://github.com/CaltechOpticalObservatories/gecko.git
$ cd gecko
$ python3 -m pip install --user psutil
$ ./gecko --version

On Debian 12, Ubuntu 23.04 and newer, pip install --user is blocked for the system Python. Install psutil with sudo apt install python3-psutil instead.

./gecko can be symlinked onto the PATH (sudo ln -s "$PWD/gecko" /usr/local/bin/gecko). Unlike before 0.2, it now works from any directory.

Configure#

Run the interactive setup once. It explains each section and asks for the values:

$ gecko -init

Press Enter at a prompt to keep the value shown in parentheses. See configuration for what each setting does.

Where the configuration lives#

Gecko uses the first file that exists from this list:

The path given with -c / --config
The path in the GECKO_CONFIG environment variable
~/.config/gecko/gecko.ini (or $XDG_CONFIG_HOME/gecko/gecko.ini)
/etc/gecko/gecko.ini

gecko -init writes to the path from --config or GECKO_CONFIG if one is given, and otherwise to ~/.config/gecko/gecko.ini.

One config shared by all accounts on a machine: create it in /etc and every user picks it up automatically:

$ sudo /opt/gecko/bin/gecko -init --config /etc/gecko/gecko.ini

Make sure the account operators use can write to the configured report_path.

Check the setup#

File a test report:

$ gecko -u "$USER" -m "Test report after installing Gecko"

Open the bundle it prints and check it against what’s in a report. If screenshots or logs are missing, see troubleshooting.

Upgrading from a source checkout older than 0.2#

Before 0.2, gecko -init saved settings inside the repository, in triage_package/triage.ini. Version 0.2 moves that file, so git pull will refuse to run while it has local changes. Save your settings first:

$ cd /path/to/gecko
$ mkdir -p ~/.config/gecko
$ cp triage_package/triage.ini ~/.config/gecko/gecko.ini
$ git checkout -- triage_package/triage.ini
$ git pull

Then run gecko -u "$USER" -m "test" to confirm the settings were picked up.

If you run a newer Gecko while an initialized triage_package/triage.ini is still present, Gecko uses it and prints a warning asking you to move it. gecko -init also copies its values into the new location automatically.