vnctalk-prosody/AGENTS.md

AGENTS.md — vnctalk-prosody

What this repo is

Dockerized Prosody 0.11.6 XMPP server for VNCtalk. It builds Prosody from source, applies patches to core upstream files, and bundles custom Lua modules. There is no language package manager or test framework.

Build & verification

• Only build command: docker build -t <tag> .
• No make, npm, rockspec tests, or linting exists.
• test.sh is a manual integration helper that runs the container with a long list of required env vars. It is not an automated test suite.
• Python test suite lives in tests/. It is an optional pytest/slixmpp integration suite used to verify a running XMPP server against VNCtalk requirements.
  • Set up: python3 -m venv tests/venv && source tests/venv/bin/activate && pip install slixmpp pytest pytest-asyncio aiohttp
  • Run dry (no server): pytest tests/ -v --skip-live -c tests/pytest.ini
  • Run against a server: set XMPP_JID, XMPP_PASSWORD, XMPP_DOMAIN, MUC_DOMAIN, etc., then pytest tests/ -v -c tests/pytest.ini

Code layout

Path	Purpose
patches/	Overrides for upstream Prosody core files (e.g., mod_mam.lua, mod_muc.lua, moduleapi.lua). Copied over the upstream source during the Docker build.
vnctalk/	Custom Prosody Lua modules. Copied wholesale to /usr/local/lib/prosody/modules/ in the image.
config/	Runtime templates and shell scripts.

• patches.list is stale and unused by the build; the Dockerfile hardcodes each cp command. If you add a patch, update the Dockerfile RUN cp … block.

Configuration

• The real config source is config/prosody.cfg.lua.template. At container startup, startup.sh renders it with envsubst to /etc/prosody/prosody.cfg.lua.
• Edit the template, not a generated .cfg.lua file.
• Template variables use ${VAR} syntax. Required runtime env vars include: prosodyDomain, prosodyDBhost, prosodyDBname, prosodyDBuser, prosodyDBpass, hybridaAuthUrl, fcmApiKey, fcmApiUrl, fileShareBaseUrl, fileShareSecret, avatarUploadUrl, avatarUploadUser, avatarUploadPass.

Runtime quirks

• startup.sh (main container) generates certs, renders config, and runs /usr/local/bin/prosody -F.
• startup-sidecar.sh runs a separate Node http-server on port 8080 for static files (redirect page, status page). This is not the XMPP server.
• healthcheck.sh compares /etc/tls-update/tls.crt with the currently loaded cert. If they differ, it exits 2 (not 1) to force a container restart so the new cert is picked up. It then checks TCP port 5582 (admin telnet).

CI / deploy

• GitLab CI (.gitlab-ci.yml). Builds push to Google Container Registry (eu.gcr.io).
• main branch builds a development image.
• Git tags matching prod-* or stable-* trigger promotion jobs that retag the existing dev image rather than rebuilding.

Module conventions

• Lua 5.2. Modules follow Prosody conventions (module:hook, module:open_store, module:get_option_string, module:provides).
• Authentication is delegated to an external HTTP endpoint via mod_auth_http_async.
• Push notifications are handled by mod_vnc_fcm (and mod_vnc_fcm_hin) using a configurable FCM proxy URL.
• mod_http_rest exposes an HTTP endpoint at /rest that accepts text/xml bodies and injects them as XMPP stanzas into the server.