# Onboarding

What a new person needs to work on this.

## Run it locally, no infrastructure

Ruby 3.2+ is all you need. From the repo root:

```
ruby components/backend/server.rb
```

The console is at http://127.0.0.1:4000. This uses a JSON file for storage and built-in dev
credentials, so there's nothing to configure. To run on PostgreSQL instead, see the README.

Run the tests from `components/backend` with `make test` (or any `test/*.rb` file directly). To watch a
full call without a phone, start the server and run `ruby sim/simulator.rb`.

## GitLab access

The repo is https://gitlab.vmin.cz/vm/helpdesk. Ask an owner to add you to the `vm` group, then clone
over SSH (vmin git is SSH-only):

```
git clone git@gitlab.vmin.cz:vm/helpdesk.git
```

The pipeline (lint, tests, e2e) runs on every push. We own this repo and push straight to `master`;
branches are for work you want to park, not ceremony. Production only changes when someone clicks the
manual deploy job on a green pipeline - see `docs/operations.md`.

## SSH with a yubikey

vmin git and servers authenticate with your OpenPGP-card SSH key, which gpg-agent hands to ssh. Check
it's loaded:

```
ssh-add -L        # shows your "cardno:" key
```

Every push and server login needs a physical touch on the key. If a push fails with "agent refused
operation", your PIN cache has expired: run any ssh once, enter the PIN, touch the key, then retry.

## The operator certificate

Operators reach the console over mutual TLS with a vmin client certificate (the same PKI as
whisper.cajk.org). You need it installed in your browser to open https://moje.al.army. Ask for a vmin
cert if you don't have one. On iOS, use Safari - Brave on iOS can't present client certificates.

If your `.p12` is old enough that OpenSSL 3 refuses to read it ("unsupported algorithm" or a bare
"Error outputting keys and certificates"), re-export it once:

```
openssl pkcs12 -legacy -in old.p12 -nodes -out tmp.pem     # asks for the p12 passphrase
openssl pkcs12 -export -in tmp.pem -out new.p12            # set a passphrase for the new file
shred -u tmp.pem                                           # tmp.pem holds the key unencrypted
```

Import `new.p12` into the browser and delete the intermediates.

## Next

- `docs/architecture.md` - how it fits together.
- `docs/operations.md` - the server and the pipeline.
- `docs/device-api.md` - the phone-to-backend contract, if you're touching either side of it.