git-annex/ tips/ Systemd unit

/!\ THIS PAGE IS A DRAFT /!\

## Introduction

Systemd is a suite of tools for system and user daemon management.

It can be used as an alternative to XDG autostart files to start the git-annex daemon and optionally the webapp, either at startup (system service) or when an user logs in (user service).

## Setup

### User service

Sample unit file (`/etc/systemd/user/git-annex.service`):

    [Unit]
    Description=git-annex assistant daemon

    [Service]
    ExecStart=/usr/bin/git-annex assistant --autostart --foreground
    Restart=on-failure

    [Install]
    WantedBy=default.target

Commands for enabling and starting the service as the current user:

    systemctl --user enable git-annex.service
    systemctl --user start git-annex.service

Usually services in `default.target` start during login. (Note however that they also delay the login process.) However, if you enable "linger" via `loginctl`, then these services start on boot instead.

### System service

If for some reason you cannot use `systemd --user`, the other option is to have system-wide services:

Sample unit file (`/etc/systemd/system/git-annex@.service`):

    [Unit]
    Description=git-annex assistant daemon
    After=network.target

    [Service]
    User=%i
    ExecStart=/usr/bin/git-annex assistant --autostart --foreground
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target

Commands for enabling and starting the service as user `u`:

    systemctl enable git-annex@u.service
    systemctl start git-annex@u.service

## Considerations

### Webapp

The webapp may be started instead of the assistant, by launching the associated command in the unit file. This will run an associated assistant automatically. However, it may also attempt to open a potentially unwanted browser window.

    ExecStart=git-annex webapp

TODO: try this.

### Encrypted home directory

Users may store their keyring and repositories in their encrypted home directory mounted at login. This may break a system service running at boot.

TODO: try this.

### Common daemon

One daemon may be used to sync repositories for multiple users. For this, it might be helpful to make use of ACLs to access other user directories.

## References

- systemd.unit man page
- systemd on ArchWiki
- TL;DR Syncthing with systemd documentation
- Syncthing systemd unit files

comment 2

@oberix, the --autostart --foreground combination is only supported properly since git-annex version 6.20170214. Before that, the --forground was ignored when using --autostart.

Comment by joey — Tue Jul 22 18:11:47 2025
autostart and foreground together doesn't seem to work

With systemd using `--autostart --foreground` either ignore foreground or quit immediatelly.

I managed to have the process stay alive with `RemainAfterExit=on`:

    [Service]
    User=%i
    ExecStart=/usr/bin/git-annex assistant --autostart --foreground
    ExecStop=/usr/bin/git-annex assistant --autostop
    RemainAfterExit=on
    Restart=on-failure
    RestartSec=5

but git-annex processes does not maintain the `--foreground` option which is causing a lot of zombies in the long period (not totally clear why).

My current solution is to have a service for each annex repository and avoid `--autosart` but this is annoying because it require to pass the path as `%I` and wrap git-annex in bash script to get the repo owner as the user.

Comment by oberix — Tue Jul 22 18:11:47 2025
Comments on this page are closed.