Skip to content

Client Install

Jump to bottom
Hamish edited this page Jul 26, 2026 · 5 revisions

Client Ping Service Installation & Uninstallation Guide

This wiki page describes how to install, configure, verify, and uninstall the Indi-Allsky Map Ping Client on camera host machines. This client periodically pings the central Allsky Map server with status updates, site metadata, and the latest camera image.

Service Overview

The client setup relies on four primary components:

  1. Script: allsky-map-ping - The Python 3 script that reads the configuration, copies/reads the latest image, and pings the API.
  2. Configuration: /etc/allsky-map/ping.conf - Holds your API key, target server URL, coordinates, and local file paths.
  3. Systemd Service: allsky-map-ping.service - Executes the python script under a restricted system user.
  4. Systemd Timer: allsky-map-ping.timer - Triggers the service periodically (by default every hour, with randomized delay jitter to distribute server load).

Method 1: Automated Installation & Uninstallation (Recommended)

An interactive script install.sh is provided to automate user/group configuration, systemd setup, directory permissions, and validation check routines.

Installation

  1. Navigate to the services directory on your camera host: 
    cd services/
  2. Execute the installer script as root: 
    sudo bash install.sh
  3. The script will guide you through interactive prompts:
    • API Key: The unique camera client API Key generated on the map frontend (should match the format allsky_live_<uuid>).
    • Camera metadata: Camera name, owner name/handle (optional), latitude, longitude, and optional camera website URL.
    • Image path detection: The installer searches for a local /etc/indi-allsky/flask.json to extract the correct path for latest.jpg. If it cannot find it, you will be prompted for your image directory.
  4. The installer automatically performs the following tasks:
    • Checks that Python 3 is installed.
    • Creates a dedicated system user allsky-map if it doesn't already exist.
    • Installs the python script to /usr/local/bin/allsky-map-ping.
    • Writes configuration details to /etc/allsky-map/ping.conf with secure permissions (chown root:allsky-map, chmod 640).
    • Installs the systemd service and timer configurations.
    • Starts and enables the systemd timer.
    • Triggers an immediate test ping and prints the result to verify connectivity.

Note

The configuration file /etc/allsky-map/ping.conf contains your unique API_KEY. Restricting permissions to 640 ensures that other users on the system cannot read it, while the allsky-map system service user can.

Uninstallation

To remove all installed components automated by the script, run:

sudo bash install.sh --uninstall

This will:

  • Stop and disable the allsky-map-ping.timer.
  • Remove the service and timer unit files from /etc/systemd/system/.
  • Reload the systemd daemon.
  • Remove the installed script executable /usr/local/bin/allsky-map-ping.

Warning

The uninstaller does NOT delete your configuration file at /etc/allsky-map/ping.conf or the system user allsky-map. This prevents accidental loss of your API Key and coordinates. If you want to purge these components as well, execute the following manually:

sudo rm -rf /etc/allsky-map
sudo userdel allsky-map

Method 2: Manual Installation & Uninstallation

If you prefer to set up the client service manually, follow the step-by-step instructions below.

Manual Installation

1. Copy the Executable Script

Copy the python client script to /usr/local/bin and make it executable:

sudo cp allsky-map-ping /usr/local/bin/allsky-map-ping
sudo chmod 0755 /usr/local/bin/allsky-map-ping

2. Create the System User

For security, create a dedicated system user without login privileges or a home directory:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin --user-group allsky-map

3. Set Up Configuration File

Create the configuration directory, copy the configuration template, and edit it:

sudo mkdir -p /etc/allsky-map
sudo cp allsky-map-ping.conf /etc/allsky-map/ping.conf
sudo nano /etc/allsky-map/ping.conf

Inside /etc/allsky-map/ping.conf, set your parameters:

API_URL="https://allsky-map.com/api/ping"
API_KEY="allsky_live_YOUR_UUID_HERE"

CAMERA_NAME="My Camera Name"
CAMERA_OWNER="My Name"
CAMERA_LAT="12.3456"
CAMERA_LNG="-76.5432"
CAMERA_SITE_URL="https://mycamerawebsite.com"
CAMERA_IMAGE_PATH="/home/pi/allsky/images/latest.jpg"

Apply secure permission levels to lock down the API key:

sudo chown root:allsky-map /etc/allsky-map/ping.conf
sudo chmod 0640 /etc/allsky-map/ping.conf

4. Install Systemd Files

Copy the service and timer definitions to the system service directory:

sudo cp allsky-map-ping.service /etc/systemd/system/
sudo cp allsky-map-ping.timer /etc/systemd/system/
sudo chmod 0644 /etc/systemd/system/allsky-map-ping.service
sudo chmod 0644 /etc/systemd/system/allsky-map-ping.timer

5. Enable and Start the Timer

Reload systemd, enable the timer to start automatically at boot, and run it immediately:

sudo systemctl daemon-reload
sudo systemctl enable --now allsky-map-ping.timer

Manual Uninstallation

To completely clean up the manual installation, run the following commands sequentially:

# 1. Stop and disable the systemd timer
sudo systemctl disable --now allsky-map-ping.timer

# 2. Delete the systemd files
sudo rm -f /etc/systemd/system/allsky-map-ping.service
sudo rm -f /etc/systemd/system/allsky-map-ping.timer

# 3. Reload systemd configuration to clear the unit definitions
sudo systemctl daemon-reload

# 4. Remove the script executable
sudo rm -f /usr/local/bin/allsky-map-ping

# 5. Remove the configuration directory
sudo rm -rf /etc/allsky-map

# 6. Remove the system user and user group
sudo userdel allsky-map

Operations & Troubleshooting

Check Service and Timer Status

To verify the timer is enabled and active:

systemctl status allsky-map-ping.timer

To see when the timer is next scheduled to fire:

systemctl list-timers --all | grep allsky-map-ping

Test/Trigger a Ping Manually

You can force the ping service to execute instantly outside the timer interval by calling the service target:

sudo systemctl start allsky-map-ping.service

Read the Logs

Check stdout/stderr logs produced by execution:

journalctl -u allsky-map-ping.service -n 50

To tail the logs in real time:

journalctl -u allsky-map-ping.service -f

Common Issue: File Permissions for Camera Images

Because the service runs under the unprivileged allsky-map user, the script might fail to read the image path specified by CAMERA_IMAGE_PATH.

If you receive a permission error in the journal logs, run:

sudo -u allsky-map test -r /path/to/your/latest.jpg && echo "Readable" || echo "Not Readable"

If this prints Not Readable, ensure:

  1. The image file itself has read access granted to the user or is readable by all (e.g., chmod 644).
  2. Every parent directory in the path leading to the image file has execute permissions for all or is owned by the same group (e.g., chmod +x on the parent directories).

Clone this wiki locally