> ## Documentation Index
> Fetch the complete documentation index at: https://watchdog.sdslabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyhouse Sync

> How Watchdog pulls access changes from Keyhouse and applies them to the server, without a separate webhook server.

### What is Keyhouse?

What do we do if we cannot ensure a database that is almost always live? Well, host your database as a GitHub repository ;) That's what we did, and it has worked very well.

The first thing to look at should be the structure of Keyhouse.

![Keyhouse repository structure](https://mintcdn.com/watchdog-docs/jan3tIWKPXZCjmik/images/hLr8AsappF8wN1ZeS0Qa.png?fit=max\&auto=format\&n=jan3tIWKPXZCjmik\&q=85\&s=f267e47463c9e18d5e8aa0ace06b549e)

*tl;dr* the folder `keys` contains the SSH keys of all members, and the `hosts` folder contains a file for each member listing the servers and groups they can access.

Let's have a look at Keyhouse.

![Keyhouse folder layout](https://mintcdn.com/watchdog-docs/jan3tIWKPXZCjmik/images/syWYibiENOqE5LomRogh.png?fit=max\&auto=format\&n=jan3tIWKPXZCjmik\&q=85\&s=d7d0b68ba5333b30c3a9b937b41d2c9c)

To register yourself as a part of an organization (and get a username), add your SSH key to the file `data/keys/<name>`. Make sure the name you choose doesn't collide with someone else's.

![Adding an SSH key to Keyhouse](https://mintcdn.com/watchdog-docs/jan3tIWKPXZCjmik/images/b7QR3YLfEJjkAZvVbS8g.png?fit=max\&auto=format\&n=jan3tIWKPXZCjmik\&q=85\&s=805645500726006306306e0d9144a7b9)

To gain access to the group `study` in the server called `ratchet`, we edit our own file `data/hosts/<name>` (the same `<name>` as our key file) to add the line `ratchet|study` at the bottom, open a pull request

![Adding an access line to a hosts file](https://mintcdn.com/watchdog-docs/jan3tIWKPXZCjmik/images/j9pkX8U0AI2YFxc2nECm.png?fit=max\&auto=format\&n=jan3tIWKPXZCjmik\&q=85\&s=a0937d2c81bcbeb10e9f62c334d05269)

and get it merged by an admin.

![Pull request merged by an admin](https://mintcdn.com/watchdog-docs/jan3tIWKPXZCjmik/images/zecpok86Cyj26gmOaAmo.png?fit=max\&auto=format\&n=jan3tIWKPXZCjmik\&q=85\&s=254491d8cb27bc31638ad336282769fd)

As simple as that! You got access to group `study` on server `ratchet` (no, not really, we won't give you access to our ratchet).

### How does Watchdog sync with Keyhouse?

Watchdog pulls changes from Keyhouse itself, so there's no separate webhook server to run or expose. The sync logic lives in the [`watchdog_utils_II`](https://github.com/sdslabs/watchdog-utils) crate, which Watchdog depends on directly.

#### What Watchdog reads

When your pull request is merged, Keyhouse's build workflow turns the `data/` folder into an API tree on the `build` branch. That branch, not `data/`, is what Watchdog reads:

```
build branch
├── names/
│   └── <user-hash>          # holds the username
└── access/
    └── <server>/
        └── <group>/
            └── <user-hash>  # grants access
```

`<user-hash>` is the SHA-256 of the member's SSH key. Your `ratchet|study` line from above becomes `access/ratchet/study/<your-hash>`.

#### Incremental sync (`watchdog update`)

Watchdog can be triggered by CI, cron, or an SSH login; see [Setup](https://watchdog.sdslabs.co/setup.md#keeping-watchdog-in-sync-with-keyhouse). Whichever way it's triggered, the sync runs the same steps:

**1. Read the last synced commit**

Watchdog stores the last commit it synced in `/opt/watchdog/bin/base_commit.txt`.

**2. Fetch the diff**

It fetches the latest commit on the `build` branch and asks GitHub for the diff since the last synced commit.

**3. Filter for this server**

It keeps changes under `access/<server>/...` where `<server>` matches this server's `hostname`, plus `names/` changes.

**4. Apply the changes**

It creates users as needed, adds or removes them from Unix groups, and deletes a user once they have no groups left on this server.

**5. Save the new commit**

It writes the new commit hash to `base_commit.txt`, so the next sync only looks at what changed since.

> [!NOTE]
>
> Groups must already exist on the server; Watchdog doesn't create them. The
> `sudo` group is mapped to the server's `sudo` or `wheel` group.

#### Full sync (`watchdog update --all`)

A full sync skips the diff. It downloads the entire `build` tree into a local cache, reconciles every user and group on the server against it, and records the latest commit in `base_commit.txt`. Run it once on a fresh install, and any time you want to resync from scratch.

#### When things go wrong

| Situation | What happens |
| - | - |
| `base_commit.txt` is missing or empty (e.g. a fresh install) | `watchdog update` stops with an error asking you to run `watchdog update --all` first. |
| GitHub can't be reached, or the commit/diff fetch fails | Watchdog reconciles users from the local cache of the last full sync, so the server keeps its last known access list. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.