be9f14ce34
A small helpdesk system: an office Pixel running a patched GrapheneOS Dialer answers technician calls, records both call legs as separate channels, and a Ruby backend transcribes them through Whisper and files an AI summary against the caller. Squashed to a single commit for sharing. No credentials are included; secrets live outside the repo in /etc/helpdesk/env on the server or a gitignored .claude/env.local locally. See .claude/env.local.example for the shape. Start at README.md, then docs/architecture.md.
65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# 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.
|