Installing HISPEC on a host#

This is the one way to put the HISPEC software on an instrument host. It is a root job for whoever administers the machine; operators never need it to deploy, start or debug daemons. The host-specific build notes (Build Setup for HISPEC and HSDEV User, HISPEC FEI Server: Headless Real-time Build) cover the OS, packages and hardware, and link back here for the software.

What you end up with#

Path	What it is
`/opt/hispec/app`	the hispec checkout the daemons run from
`/opt/hispec/venv`	the virtualenv, built by `uv` from that checkout
`/etc/hispec`	deployed configs and instance files, plus `secrets.env` and the host role
`/var/log/hispec`	the daemons’ own log files

The daemons run as the unprivileged hispec system account. People log in as themselves (or the shared hsdev) and are members of hispec-ops, which owns /opt/hispec and /etc/hispec. Members can pull, hotfix, sync the venv, edit configs and start or stop daemons without sudo. A default ACL keeps files added later group-writable, whatever the creator’s umask.

secrets.env and the GitHub token stay root-owned, and /var/log/hispec is written only by the daemons.

The venv’s bin is on every login shell’s PATH, set by /etc/profile.d/hispec.sh, so python, libby and hispec work without activating anything.

Install#

Prerequisites. The OS packages in the build notes, plus:
```
sudo apt install -y acl git curl
```

Clone, with submodules:

sudo git clone --recurse-submodules \
    https://github.com/CaltechOpticalObservatories/hispec.git /opt/hispec/app

Install the deploy key. uv lock reads every extra on every host, and the tracking camera repo is private, so each host needs its read-only key:
```
sudo install -D -m 600 -o root -g root <deploy-key> /etc/hispec/deploy-key
```
The key is generated once and registered as a read-only deploy key on hispec-tracking-camera-instrument; every host gets a copy of the same private half.
Run the installer, naming every account that operates this host:
```
sudo /opt/hispec/app/systemd/install.sh hsdev alice bob --host-role <role>
```
--host-role is the name instance files use in HISPEC_HOST (hispecserver, feiserver, …). Leave it out to use the short hostname. It is written once, to /etc/hispec/host; edit that file to change it.

A host that runs the tracking camera adds --extra atcam, which builds the camera module into the venv. Extras are recorded in /etc/hispec/extras, so later runs keep them; hispec doctor reports one that has gone missing.
Log out and back in, so the new groups and PATH take effect.
Add the credentials this host’s daemons need:
```
$EDITOR /etc/hispec/secrets.env
```
Secrets lists the variables. hispec doctor says which are still missing.
Check the host:
```
hispec doctor
```
Deploy and start daemons, as yourself: Running the HISPEC Daemons with systemd from here on.

What install.sh does#

It bootstraps a pinned uv, runs uv lock --upgrade and uv sync --all-packages into /opt/hispec/venv, then hands over to hispec install. That command comes from instrumentctl, whose README describes every step. It is shared with other instruments, so HISPEC only supplies src/hispec/cli/instrument.toml.

Re-running it#

install.sh is idempotent and reports only what it changes. Re-run it:

to enrol another operator: sudo /opt/hispec/app/systemd/install.sh carol;
after a pull that changed dependencies, or to pick up merged libby fixes, since the lock is refreshed each run;
to repair anything hispec doctor flags.

Neither adding a daemon nor picking up code changes needs it. A git -C /opt/hispec/app pull followed by hispec deploy or hispec restart covers both, with no sudo.

Development checkouts#

Your own clone for development is separate from all of this. Build it with uv sync --all-packages as the README describes, then use uv run. The PATH entry for /opt/hispec/venv does not get in the way, since uv run uses the project’s .venv.