95 lines
3.8 KiB
Markdown
95 lines
3.8 KiB
Markdown
# vnctalk-avatar
|
|
|
|
The VNCtalk **avatar service** — a small Node/nginx service that preprocesses
|
|
(GraphicsMagick resize) and serves user avatars. This is the code that backs
|
|
`avatar.vnc.biz`; deployed in-cluster it becomes the dev cluster's avatar store.
|
|
|
|
## What it does
|
|
|
|
On `PUT /avatarupload/<jid>` it receives raw image bytes, resizes them to a
|
|
fixed set of resolutions, and writes them to `outputDir` keyed by `md5(jid)`:
|
|
|
|
```
|
|
<outputDir>/<md5(jid)>.jpg # default resolution (80)
|
|
<outputDir>/<md5(jid)>-<res>.jpg # 46, 47, 57, 80, 420, 800
|
|
```
|
|
|
|
The frontend reads these back via `avatarServiceUrl + "/" + md5(jid) + "-<size>.jpg"`.
|
|
Prosody's `vnc_vcard_avatar` module is what `PUT`s the photo here on every vCard
|
|
avatar change (`avatar_upload_url` → `<avatar-host>/avatarupload/`).
|
|
|
|
## API
|
|
|
|
| Method | Path | Purpose |
|
|
|---|---|---|
|
|
| `PUT` | `/avatarupload/:jid` | Upload avatar bytes (`Content-Type: image/*`); returns `md5(jid)`. |
|
|
| `DELETE` | `/avatarupload/:jid` | Remove all of a jid's avatar files. |
|
|
| `GET` | `/avatarupload/health` | `{"status":"OK"}`. |
|
|
| `POST` | `/avatarupload/info` | Batch `ctime` lookup for a list of md5 ids. |
|
|
|
|
Static image serving (`GET /<md5>.jpg`) is **not** handled by `app.js` — it is
|
|
served by an nginx that shares the `outputDir` volume. The container installs
|
|
nginx but the static-serving server config must be supplied at deploy time (see
|
|
Deploy below).
|
|
|
|
## Auth
|
|
|
|
`PUT`/`DELETE` require either:
|
|
|
|
- the legacy global Basic credentials (`avatar` / the shared avatar-server
|
|
password), or
|
|
- a JWT (Bearer/basic-password slot) signed with `config.jwtsecret` whose
|
|
`vncdomain` claim matches the jid's domain.
|
|
|
|
> **Open item:** both the global Basic credential hash and `jwtsecret` are
|
|
> hardcoded in `app/app.js` / `config/vnc-avatarservice.js`. These are shared
|
|
> service credentials already committed elsewhere (vncdirectory/vncproject).
|
|
> For a clean in-cluster deploy they should move to env vars / Infisical —
|
|
> tracked separately.
|
|
|
|
## Config (`config/vnc-avatarservice.js`)
|
|
|
|
| Key | Default | Purpose |
|
|
|---|---|---|
|
|
| `servicePort` | `3896` | Node upload API port. |
|
|
| `outputDir` | `/var/opt/out` | Avatar filesystem store (needs a persistent volume). |
|
|
| `defaultresolution` | `80` | `.jpg` (no suffix) resolution. |
|
|
| `resolutions` | `[46,47,57,80,420,800]` | All sizes written on upload. |
|
|
| `jwtsecret` | hardcoded | JWT verification secret (move to env). |
|
|
|
|
`NODE_ENV` selects the config block (`development` / `development2` / `gr13`).
|
|
|
|
## Build
|
|
|
|
```bash
|
|
docker build -t vnctalk-avatar .
|
|
# CI: push to main → .gitea/workflows/build.yml → kaniko
|
|
```
|
|
|
|
## Deploy
|
|
|
|
Not yet declared in `vnc-iac-env`. Two prerequisites for a working in-cluster
|
|
deploy (tracked separately):
|
|
|
|
1. **Persistent `outputDir`** (`/var/opt/out`) — otherwise avatars are lost on
|
|
pod restart.
|
|
2. **nginx static serving** — a server block (or ingress) that serves the
|
|
`outputDir` files at `avatarServiceUrl`, plus the CORS headers the browser
|
|
needs.
|
|
|
|
Once deployed, point `vnctalk-prosody`'s `avatar_upload_url` at it
|
|
(`https://<avatar-host>/avatarupload/`) and set `avatar_upload_user` /
|
|
`avatar_upload_pass` (from Infisical `AVATAR_PASSWORD`, not git).
|
|
|
|
## Layout
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `app/app.js` | Express upload API (`PUT /avatarupload/:jid`, health, info). |
|
|
| `config/vnc-avatarservice.js` | Env-selected config (port, outputDir, resolutions, jwtsecret). |
|
|
| `Dockerfile` | Alpine multi-stage, non-root (`vnc`, uid 1001), gm + nginx + node. |
|
|
| `Dockerfile.ubuntu` | Legacy GCP base-image variant (pm2 + deb `vnc-avatarservice`). |
|
|
| `debian/` | Legacy Debian packaging (used by the GCP-era image). |
|
|
| `conf.template/` | Legacy passenger/nginx templates (mostly notification-proxy leftovers). |
|
|
| `.gitea/workflows/build.yml` | kaniko build → `vnclagoon/vnctalk-avatar:{sha-…,latest}`. |
|