# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

This repo builds a Docker image that packages [Prosody](https://prosody.im/) (XMPP server) with VNCtalk-specific
customizations: custom Lua modules, patches to upstream Prosody core/modules, and container startup/config tooling.
There is no application source beyond Lua modules and shell/config templates — the "build" is the Dockerfile.

## Repository layout

- `Dockerfile` — multi-stage build. Builder stage compiles Prosody 0.12.6 from source against Alpine packages
  (with `--idn-library=idn`; the 0.12+ ICU default breaks at runtime because the image ships no ICU data);
  final stage copies the built `/usr/local/` tree, then layers on `vnctalk/` and `config/`.
- `patches/` — unified diffs against the pristine Prosody source tree, applied in the Dockerfile builder stage
  with `patch -p1 --fuzz=0` before `./configure && make install`. Paths inside each patch are relative to the
  source root, so adding/removing a `.patch` file needs no Dockerfile change. `patches/README.md` documents each
  patch's intent; `upgrade-plan.md` (repo root) tracks their per-version disposition.
- `vnctalk/` — original VNCtalk-authored Prosody modules (own module directory tree), copied wholesale into
  `/usr/local/lib/prosody/modules/` in the image. Some are single `.lua` files, others are subdirectories with
  their own `README.markdown`/`README.wiki` (following the upstream prosody-modules convention).
- `config/` — templates and scripts rendered/run at container start:
  - `prosody.cfg.lua.template` — the Prosody config, templated with `envsubst` using environment variables
    (`prosodyDomain`, `prosodyDBhost/name/user/pass`, `fcmApiKey`, `hybridaAuthUrl`, `fileShareBaseUrl`,
    `fileShareSecret`, `avatarUploadUrl/User/Pass`, etc.). This is the map of every configurable knob — check it
    before assuming a setting doesn't exist.
  - `startup.sh` — main container entrypoint (`CMD` in Dockerfile): writes TLS cert/key (from env or a baked-in
    dev default, overridden by files in `/etc/tls-update/` if present), renders `prosody.cfg.lua` via `envsubst`,
    then execs `prosody -F`.
  - `startup-sidecar.sh` — separate entrypoint for a static-file/redirect sidecar (renders `index.html.template`,
    serves `/etc/prosody/public/` via `http-server` on :8080). Not invoked by the main Dockerfile `CMD`; used as
    an alternate command for a sidecar container in the deployment.
  - `healthcheck.sh` — container healthcheck: fails (exit 2) if a new TLS cert is present in `/etc/tls-update/`
    but not yet picked up (to force a restart), otherwise checks the Prosody telnet admin port (5582) via
    `check_tcp`.
  - `default.conf.template` — nginx-style static server block (used by the sidecar/static-serving path).
- `test.sh` — not an automated test suite; a manual `docker run` invocation with example env vars for local
  smoke-testing an image build (`./test.sh <image-tag>`). There are no unit/integration tests in this repo.
- `scan/` — CI artifact output directory (Trivy image scan results), not source.

## Build / run

- Build the image: `docker build -t vnctalk-prosody .`
- Smoke-test locally: `./test.sh vnctalk-prosody` (edit the env vars in `test.sh` for your local DB/auth backend
  first — it points at example hosts/creds).
- No linter or automated test command exists for this repo; verification is "does the image build and does
  Prosody start against the rendered config" (see `test.sh` and `config/startup.sh`).

## CI/CD (`.gitea/workflows/deploy.yml`)

- `main` branch pushes: build the image with kaniko (daemon-less, fetched via `crane`) and push to the
  Gitea registry as `gitea.saas.vnc.biz/vnciac/vnctalk-prosody:sha-<short-sha>` and `:latest`.
- Registry auth comes from the Gitea Actions secrets `REGISTRY_USER` / `REGISTRY_TOKEN`.
- The image is deployed by the ArgoCD application in the `vnc-iac-env` GitOps repo
  (`dev/charts/vnctalk-prosody`), not by any manifest in this repo.

## Working with patches vs. vnctalk modules

- If a change is to *upstream* Prosody behavior (core or a module that ships with Prosody, e.g. `mod_mam`,
  `mod_muc`, `mod_carbons`, `moduleapi.lua`, `portmanager.lua`), it belongs in `patches/` as a unified diff
  with `a/<source-relative-path>` / `b/<source-relative-path>` headers (picked up automatically by the builder
  stage). Document it in `patches/README.md`. Use `--fuzz=0`-clean hunks — a fuzzy patch fails the build by design.
- If a change is VNCtalk-specific new functionality (module name starts with `mod_vnc_*`, or is otherwise
  VNCtalk-original like `mod_alias`, `mod_webpresence`, `mod_http_rest`), it belongs in `vnctalk/`.
- When adding a new module (either kind), remember to add it to `modules_enabled` (or the relevant
  `Component`'s `modules_enabled`) in `config/prosody.cfg.lua.template`, or it will be installed but inactive.
- `prosody.cfg.lua.template` defines three hosts: the main `VirtualHost "${prosodyDomain}"` (HTTP-async auth
  backend), `VirtualHost "anon.${prosodyDomain}"` (anonymous auth), and `Component "conference.${prosodyDomain}"
  "muc"` (the MUC/group-chat component, with its own module list and MAM/logging config) — module and config
  changes usually need to target one specific host/component, not the global `modules_enabled` list.