macanhhuy
d6dddbbc91
Build + push image / build-and-push (push) Successful in 1m8s
Replace eu.gcr.io/vnc-development image refs with gitea.saas.vnc.biz/vnciac, swap gcr-json-key pull secret for gitea-registry, and update CI/deploy docs from GitLab CI to Gitea Actions.
72 lines
5.3 KiB
Markdown
72 lines
5.3 KiB
Markdown
# 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.
|