vnctalk-prosody/CLAUDE.md

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 (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.