# Shepherd

Here we record information on running shepherd (on Debian).

# Tags

* assigned: pjotrp, efraimf
* type: documentation
* keywords: system, shepherd
* status: wip
* priority: normal

# Issues

* [ ] Currently guix system is started up using sudo as a shepherd user. This may be resolved in time when we start to use full Guix solutions
* [ ] Monitor services inside system containers

# Quick overview

On Debian the GNU shepherd can run in systemd as a 'shepherd' user because we typically run (system) containers that have root inside them.
To run the system containers and other services as different users we can use sudo.
This is not ideal, but the idea is to be able to transition to a full Guix system in the future.
Another issue is that services that run inside system containers are hard to monitor because shepherd only sees the outside of the container - at this point.

We use systemd to handle shepherd:

```
systemctl status user-shepherd.service
```

the systemd file can therefore look like:

```
[Unit]
Description=Launch user shepherd daemon
Wants=guix-daemon.service

[Service]
Type=simple
ExecStart=/var/guix/profiles/per-user/shepherd/guix-profile/bin/shepherd
User=shepherd
Group=shepherd
LimitNOFILE=8000

[Install]
WantedBy=multi-user.target
```

One advantage of using a normal user is that it is easy to test configurations as a different user on the same machine!

The process for deploying the services after creating the shepherd user is

```
symlink shepherd-services/shepherd to $HOME/.config/shepherd
symlink shepherd-services/cron to $home/.config/cron
symlink shepherd-services/*sh to $HOME
```

When shepherd starts up it should start all the services. So currently on tux02 that is bnw, gitea, ipfs, power, rn6app, singlecell and the mcron services, gitea-dump and pubmed.

To use shepherd's herd command the command is 'sudo -u shepherd
/home/shepherd/.guix-profile/bin/herd status'.

```
su shepherd
/home/shepherd/.guix-profile/bin/herd status
```

Adding a bash alias, such as "alias herd-herd='sudo -u shepherd /home/shepherd/.guix-profile/bin/herd'", will make it easier to interact with shepherd without needing to switch to the shepherd user. The logs for the various shepherd services are located in /home/shepherd/logs/ but are not yet timestamped. The log for shepherd itself is in /home/shepherd/.config/shepherd/shepherd.log. There is not yet a way to change this from a config file.