Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.allthingslinux.org/llms.txt

Use this file to discover all available pages before exploring further.

Values are loaded from .env (copy from .env.example) and optional overlays .env.dev / .env.prod. The root script scripts/prepare-config.sh substitutes ${VAR} into UnrealIRCd, Atheme, bridge, and The Lounge templates. This page documents variables used by this monorepo. The external ATL Portal uses its own env (see that repo’s docs/ENV_VARS.md); bridge auth uses BRIDGE_PORTAL_TOKEN here and BRIDGE_SERVICE_TOKEN on the portal — they must match when Portal identity is enabled.

​
How environment files work

  1. .env — baseline; copy from .env.example.
  2. .env.dev — dev overlay for just dev (from .env.dev.example).
  3. .env.prod — production-only overrides for just prod.
cp .env.example .env
cp .env.dev.example .env.dev
just dev
Compose merges .env then the overlay. apps/docs deploy (Alchemy / Workers) uses separate vars — see Docs (deployment) below; those are not in the root .env.example.

​
Core

VariableDescriptionRequiredDefault (.env.example)
PUIDContainer UID for volume ownershipNo1000
PGIDContainer GID for volume ownershipNo1000
TZTimezoneNoUTC
ATL_GATEWAY_IPAddress used in UnrealIRCd WebIRC match { ip … } blocksYes127.0.0.1 (use Tailscale or gateway IP in prod)
ATL_CHAT_IPHost IP Compose binds IRC/XMPP ports toYes127.0.0.1
LETSENCRYPT_EMAILACME registration email (cert-manager)For LEadmin@allthingslinux.org
CLOUDFLARE_DNS_API_TOKENDNS-01 API token (cert-manager)Prod LE(empty)
LOG_MAX_SIZEDocker json-file max size per log fileNo50m
LOG_MAX_FILESRotated log files to keep per containerNo5
Warning: CLOUDFLARE_DNS_API_TOKEN is highly sensitive. In local dev it is often unset; Compose may warn — safe to ignore if you are not issuing certs.

​
TLS and IRC client behaviour (explicit flags)

These are set in .env.example so dev/prod behaviour does not depend on a single ATL_ENVIRONMENT variable. scripts/prepare-config.sh uses BRIDGE_IRC_TLS_VERIFY (if set) when exporting IRC_TLS_VERIFY for UnrealIRCd-related substitution.
VariableDescriptionDefault (.env.example)
IRC_TLS_VERIFYVerify TLS when connecting to IRC (e.g. bridge → IRC)false
IRC_LOUNGE_REJECT_UNAUTHORIZEDNode TLS rejectUnauthorized for The Lounge → IRCfalse
IRC_WEBSOCKET_USE_TLSEnable TLS on UnrealIRCd listener in generated configtrue
BRIDGE_IRC_TLS_VERIFYPassed to the bridge container; prefer this for bridge-specific TLSfalse

​
IRC Service (UnrealIRCd + Atheme)

​
Build versions

VariableDescriptionRequiredDefault (.env.example)
UNREALIRCD_VERSIONUnrealIRCd image tagYes6.2.0.1
ATHEME_VERSIONAtheme image tagYesmaster
Warning: ATHEME_VERSION=master is non-reproducible. Pin for production.

​
Network identity

VariableDescriptionRequiredDefault (.env.example)
IRC_DOMAINPublic IRC hostname (TLS/SNI, cert paths)Yesirc.localhost (prod: e.g. irc.atl.chat)
IRC_ROOT_DOMAINNetwork root domainYesatl.chat
IRC_NETWORK_NAMEHuman-readable network nameYesAll Things Linux IRC
IRC_CLOAK_PREFIXCloak prefixYesatl

​
Ports

VariableDescriptionRequiredDefault
IRC_TLS_PORTTLS client portYes6697
IRC_SERVER_PORTServer link portYes6900
IRC_RPC_PORTJSON-RPC portYes8600
IRC_WEBSOCKET_PORTWebSocket portYes8000

​
Security secrets

VariableDescriptionRequiredDefault (.env.example)
IRC_CLOAK_KEY_1 … IRC_CLOAK_KEY_3Cloak keys (same on all linked servers)Yesreplace_with_cloak_key_*
IRC_OPER_PASSWORDIRC oper passwordYeschange_me_irc_oper_password
IRC_DRPASSUnrealIRCd die/restart passwordYeschange_me_drpass
IRC_SERVICES_PASSWORDUnrealIRCd ↔ Atheme link passwordYeschange_me_irc_services_password
ATL_WEBIRC_PASSWORDWebIRC shared secret (UnrealIRCd + clients)Yeschange_me_webirc_password
Warning: Replace all placeholders before any public deployment. just irc gencloak for cloak keys; hashed oper passwords: docker run --rm ghcr.io/allthingslinux/unrealircd ./unrealircd mkpasswd argon2 <password>.

​
Admin info

VariableDescriptionRequiredDefault
IRC_ADMIN_NAMEShown in /adminYesAll Things Linux
IRC_ADMIN_EMAILAdmin contactYesadmin@allthingslinux.org
IRC_STAFF_VHOSTStaff vhostNoallthingslinux.org

​
Strict Transport Security (STS)

VariableDescriptionDefault
IRC_STS_DURATIONSTS duration1m
IRC_STS_PRELOADSTS preloadno

​
TLS certificate paths (inside UnrealIRCd container)

VariableDescriptionDefault (.env.example)
IRC_SSL_CERT_PATHFullchain path…/certs/live/irc.localhost/fullchain.pem
IRC_SSL_KEY_PATHPrivate key path…/certs/live/irc.localhost/privkey.pem
Warning: Never commit private keys.

​
Atheme (reduced env surface)

.env.example only exposes the variables substituted into apps/atheme/config/atheme.conf.template. Service bot nicks/users/hosts are hardcoded in that template (or commented for optional modules) — they are not per-bot env vars in the current layout.
VariableDescriptionDefault (.env.example)
IRC_SERVICES_SERVERUnrealIRCd link services.* target hostnameOptional; default in prepare-config is ATHEME_SERVER_NAME or services.${IRC_ROOT_DOMAIN}
ATHEME_SERVER_NAMEServices server name on the networkservices.atl.chat
ATHEME_SERVER_DESCServer descriptionAll Things Linux IRC Services
ATHEME_UPLINK_HOSTUnrealIRCd hostname from Atheme container127.0.0.1
ATHEME_UPLINK_PORTUnrealIRCd listen port for services6901
ATHEME_NUMERICServer numeric00A
ATHEME_RECONTIMEReconnect interval (seconds)10
ATHEME_HTTPD_PORTJSON-RPC HTTP port8081
ATHEME_NETNAMENetwork name in Athemeatl.chat
ATHEME_HIDEHOST_SUFFIXHidden-host suffixusers.atl.chat
ATHEME_ADMIN_NAMEAdmin display nameAll Things Linux
ATHEME_ADMIN_EMAILAdmin email in configadmin@allthingslinux.org
ATHEME_REGISTER_EMAILRegistration mail from-addressnoreply@allthingslinux.org
ATHEME_SRA_BOOTSTRAP_ACCOUNTNick granted SRA on first DB initadmin
ATHEME_HELP_CHANNELHelp channel#help
ATHEME_HELP_URLHelp URLhttps://allthingslinux.org

​
Atheme service bot identities (template defaults)

The live apps/atheme/config/atheme.conf.template hardcodes nicks, users, hosts, and realnames for each service bot (NickServ, ChanServ, etc.). They are not exposed as ATHEME_* env vars in .env.example. If you fork the template, each bot follows the pattern ATHEME_<SERVICE>_NICK, _USER, _HOST, _REAL.
ServiceNickUserHostReal name
NickServNickServNickServservices.atl.chatNickname Services
ChanServChanServChanServservices.atl.chatChannel Services
OperServOperServOperServservices.atl.chatOperator Services
MemoServMemoServMemoServservices.atl.chatMemo Services
SaslServSaslServSaslServservices.atl.chatSASL Authentication Agent
BotServBotServBotServservices.atl.chatBot Services
GroupServGroupServGroupServservices.atl.chatGroup Management Services
HostServHostServHostServservices.atl.chatHost Management Services
InfoServInfoServInfoServservices.atl.chatInformation Service
HelpServHelpServHelpServservices.atl.chatHelp Services
StatServStatServStatServservices.atl.chatStatistics Services
GlobalGlobalGlobalservices.atl.chatNetwork Announcements
ALISALISalisservices.atl.chatChannel Directory
ProxyscanProxyscandnsblservices.atl.chatProxyscan Service
GameServGameServGameServservices.atl.chatGame Services
RPGServRPGServRPGServservices.atl.chatRPG Finding Services
Example: ATHEME_NICKSERV_NICK=NickServ, ATHEME_NICKSERV_USER=NickServ, ATHEME_NICKSERV_HOST=services.atl.chat, ATHEME_NICKSERV_REAL="Nickname Services".

​
WebPanel (UnrealIRCd admin UI)

VariableDescriptionDefault (.env.example)
WEBPANEL_PORTHost port mapping (infra/compose/irc.yaml)Often 8080 (optional in .env.example; uncomment to set)
WEBPANEL_RPC_USERUnrealIRCd JSON-RPC useradminpanel
WEBPANEL_RPC_PASSWORDUnrealIRCd JSON-RPC passwordchange_me_webpanel_password
Warning: RPC credentials are full admin access to UnrealIRCd’s API.

​
The Lounge

VariableDescriptionRequiredDefault
THELOUNGE_PORTPort for The Lounge web IRC clientYes9000
THELOUNGE_WEBIRC_PASSWORDWebIRC password for The Lounge to authenticate with UnrealIRCdYeschange_me_thelounge_webirc
THELOUNGE_DELETE_UPLOADS_AFTER_MINUTESAuto-delete uploaded files after this many minutesNo1440
Warning: THELOUNGE_WEBIRC_PASSWORD must match the WebIRC password configured in UnrealIRCd. Change this from the default before production deployment.

​
ObsidianIRC (optional compose fragment)

Commented examples in .env.example; enable when using infra/compose/obsidianirc.yaml. Values are build args — change .env then just obsidianirc rebuild.
VariableDescriptionExample
OBSIDIANIRC_PORTPublished port8090
OBSIDIANIRC_IRC_WS_URLBrowser → IRC WebSocketwss://irc.localhost/ws
OBSIDIANIRC_SERVER_NAMEServer label in client UIirc.localhost
OBSIDIANIRC_AUTOJOINChannels to auto-join#general

​
XMPP Service (Prosody)

Prosody reads optional tuneables from the environment in apps/prosody/config/prosody.cfg.lua. Only a subset appears in .env.example. For tables below, the Default column is the fallback when the variable is unset, as implemented in prosody.cfg.lua (not necessarily what .env.example sets).

​
Domain and admin

VariableDescriptionDefault (.env.example)
XMPP_DOMAINPrimary VirtualHost / cert identityxmpp.localhost
PROSODY_DOMAINOften set equal to XMPP_DOMAIN for templatesxmpp.localhost
PROSODY_ADMIN_JIDAdmin JID (mod_admin_adhoc, etc.)admin@xmpp.localhost
PROSODY_ADMIN_EMAILContact string in configadmin@allthingslinux.org

​
Storage

VariableDescription
(omit)Default in prosody.cfg.lua: SQLite file storage (typical dev).
PROSODY_STORAGE=sqlUse SQL backend; then set PostgreSQL vars below (see commented block in .env.example).

​
Database (only when PROSODY_STORAGE=sql)

VariableDescriptionExample
PROSODY_DB_DRIVERSQL driver namePostgreSQL
PROSODY_DB_HOSTDB hostname (compose service)xmpp-postgres
PROSODY_DB_PORTDB port5432
PROSODY_DB_NAMEDatabase nameprosody
PROSODY_DB_USERDB userprosody
PROSODY_DB_PASSWORDDB password(strong secret)
Warning: Restrict DB network access to Prosody only in production.

​
Ports

VariableDescriptionRequiredDefault
PROSODY_C2S_PORTClient-to-server portYes5222
PROSODY_S2S_PORTServer-to-server portYes5269
PROSODY_HTTP_PORTHTTP port (BOSH/WebSocket)Yes5280
PROSODY_HTTPS_PORTHTTPS port (via nginx)Yes5281
PROSODY_C2S_DIRECT_TLS_PORTDirect TLS client portNo5223
PROSODY_S2S_DIRECT_TLS_PORTDirect TLS server portNo5270
PROSODY_PROXY65_PORTSOCKS5 bytestream proxy portNo5000

​
TURN/STUN

VariableDescriptionRequiredDefault
TURN_PORTTURN server portNo3478
TURNS_PORTTURN over TLS portNo5349
TURN_SECRETShared secret for TURN authenticationYeschange_me_turn_secret
TURN_EXTERNAL_HOSTExternal hostname for TURN serverYesturn.atl.network
Warning: TURN_SECRET is a shared authentication secret. Generate a strong random value for production.

​
Security

VariableDescriptionRequiredDefault
PROSODY_OAUTH2_REGISTRATION_KEYOAuth2 registration keyYeschange_me_prosody_oauth2_registration_key (.env.example)
PROSODY_ALLOW_PLACEHOLDER_KEYAllow placeholder OAuth2 key (dev only)Notrue in example — set false in prod
PROSODY_ALLOW_REGISTRATIONAllow public registrationNofalse (cfg default when unset)
PROSODY_C2S_REQUIRE_ENCRYPTIONRequire TLS for c2sNotrue (relaxed in .env.dev)
PROSODY_S2S_REQUIRE_ENCRYPTIONRequire TLS for s2sNotrue
PROSODY_S2S_SECURE_AUTHVerified certs for s2sNotrue
PROSODY_ALLOW_UNENCRYPTED_PLAIN_AUTHPlain auth without TLSNofalse
PROSODY_MAX_CONNECTIONS_PER_IPMax connections per IPNo5
PROSODY_REGISTRATION_THROTTLE_MAXRegistrations per throttle windowNo3
PROSODY_REGISTRATION_THROTTLE_PERIODThrottle window (seconds)No3600
PROSODY_BLOCK_REGISTRATIONS_REQUIREUsername regexNo^[a-zA-Z0-9_.-]+$
PROSODY_TLS_CHANNEL_BINDINGTLS channel bindingNotrue (unset enables binding; set to false to disable)
Warning: Rotate PROSODY_OAUTH2_REGISTRATION_KEY for production; do not ship PROSODY_ALLOW_PLACEHOLDER_KEY=true publicly.

​
HTTP, upload URLs, and admin API

VariableDescriptionDefault (.env.example)
PROSODY_HTTP_HOSTHTTP bind / advertised hostlocalhost (cfg)
PROSODY_HTTP_SCHEMEhttp or httpshttp (cfg)
PROSODY_HTTP_EXTERNAL_URLBOSH/WebSocket base for clientshttp://xmpp.localhost:5280/
PROSODY_HTTPS_VIA_PROXYTerminate HTTPS at nginx/proxyfalse
PROSODY_UPLOAD_EXTERNAL_URLPublic upload URLhttps://xmpp.localhost:5281/upload/
PROSODY_PROXY_ADDRESSProxy hostname in generated URLsxmpp.localhost
PROSODY_REST_URLBase URL for mod_http_admin_apihttp://atl-xmpp-server:5280/admin_api
PROSODY_REST_TOKENBearer for admin API (Portal provisioning); just prosody-token(empty)
Legacy Basic-auth vars (PROSODY_REST_USERNAME, PROSODY_REST_PASSWORD) are not in current .env.example; prefer Bearer token.

​
TLS certificates (paths inside Prosody container)

VariableDescriptionDefault (.env.example)
PROSODY_SSL_KEYPrivate key path/etc/prosody/certs/live/xmpp.localhost/privkey.pem
PROSODY_SSL_CERTFull chain path/etc/prosody/certs/live/xmpp.localhost/fullchain.pem
Warning: Never commit private keys.

​
Logging and statistics

VariableDescriptionRequiredDefault
PROSODY_LOG_LEVELLog verbosity (debug, info, warn, error)Noinfo
PROSODY_STATISTICSStatistics backend (internal or statsd)Nointernal
PROSODY_STATISTICS_INTERVALStatistics collection intervalNomanual
PROSODY_OPENMETRICS_IPIP address for OpenMetrics endpointNo127.0.0.1
PROSODY_OPENMETRICS_CIDRCIDR range allowed to access OpenMetricsNo172.16.0.0/12

​
Message Archiving (MAM)

VariableDescriptionRequiredDefault
PROSODY_ARCHIVE_EXPIRES_AFTERArchive retention periodNo1y
PROSODY_ARCHIVE_POLICYEnable message archivingNotrue
PROSODY_ARCHIVE_COMPRESSIONEnable archive compressionNotrue
PROSODY_ARCHIVE_STOREArchive storage backend nameNoarchive
PROSODY_ARCHIVE_MAX_QUERY_RESULTSMaximum results per MAM queryNo250
PROSODY_MAM_SMART_ENABLEEnable smart MAM (archive only when needed)Nofalse (set env to true to enable)

​
MUC (Multi-User Chat)

VariableDescriptionRequiredDefault
PROSODY_MUC_NOTIFICATIONSEnable MUC notificationsNotrue
PROSODY_MUC_OFFLINE_DELIVERYDeliver messages to offline MUC participantsNotrue
PROSODY_BRIDGE_MUC_JIDBridge JID for MUC-related ACL defaults in configNobridge. + primary domain (e.g. bridge.xmpp.localhost)
XMPP_WEBCHAT_URLMUC disco#info webchat URL; {jid} → room JID. Set when using Fluux / compose that passes itNo(optional; see .env.example comment)
PROSODY_RESTRICT_ROOM_CREATIONRestrict who can create roomsNofalse
PROSODY_MUC_DEFAULT_PUBLICNew rooms are public by defaultNotrue
PROSODY_MUC_DEFAULT_PERSISTENTNew rooms are persistent by defaultNotrue
PROSODY_MUC_DEFAULT_PUBLIC_JIDSShow participant JIDs by defaultNotrue
PROSODY_MUC_LOCKINGLock rooms until configuredNofalse
PROSODY_MUC_LOG_BY_DEFAULTLog MUC messages by defaultNotrue
PROSODY_MUC_LOG_EXPIRES_AFTERMUC log retention periodNo1y
PROSODY_MUC_LOG_PRESENCESLog presence changes in MUCNofalse
PROSODY_MUC_LOG_ALL_ROOMSLog all rooms regardless of room settingNofalse
PROSODY_MUC_LOG_CLEANUP_INTERVALCleanup interval for expired logs (seconds)No86400
PROSODY_MUC_MAX_ARCHIVE_QUERY_RESULTSMaximum MUC archive query resultsNo100
PROSODY_MUC_LOG_STOREMUC log storage backend nameNomuc_log
PROSODY_MUC_LOG_COMPRESSIONEnable MUC log compressionNotrue
PROSODY_MUC_MAM_SMART_ENABLEEnable smart MAM for MUCNofalse

​
Rate limiting

VariableDescriptionRequiredDefault
PROSODY_C2S_RATEClient-to-server rate limitNo10kb/s
PROSODY_C2S_BURSTClient-to-server burst allowanceNo25kb
PROSODY_C2S_STANZA_SIZEMaximum c2s stanza size (bytes)No262144
PROSODY_S2S_RATEServer-to-server rate limitNo30kb/s
PROSODY_S2S_BURSTServer-to-server burst allowanceNo100kb
PROSODY_S2S_STANZA_SIZEMaximum s2s stanza size (bytes)No524288
PROSODY_HTTP_UPLOAD_RATEHTTP upload rate limitNo2mb/s
PROSODY_HTTP_UPLOAD_BURSTHTTP upload burst allowanceNo10mb

​
Push notifications

VariableDescriptionRequiredDefault
PROSODY_PUSH_IMPORTANT_BODYBody text for important push notificationsNoNew Message!
PROSODY_PUSH_MAX_ERRORSMaximum push errors before disablingNo16
PROSODY_PUSH_MAX_DEVICESMaximum push devices per userNo5
PROSODY_PUSH_MAX_HIBERNATION_TIMEOUTMaximum hibernation timeout (seconds)No259200
PROSODY_PUSH_NOTIFICATION_WITH_BODYInclude message body in pushNofalse
PROSODY_PUSH_NOTIFICATION_WITH_SENDERInclude sender in pushNofalse

​
Account lifecycle

VariableDescriptionRequiredDefault
PROSODY_ACCOUNT_INACTIVE_PERIODSeconds before an account is considered inactiveNo31536000
PROSODY_ACCOUNT_GRACE_PERIODGrace period before inactive account cleanup (seconds)No2592000

​
Server info

VariableDescriptionRequiredDefault
PROSODY_SERVER_NAMEServer display nameNolocalhost
PROSODY_SERVER_WEBSITEServer website URLNohttp://localhost
PROSODY_SERVER_DESCRIPTIONServer descriptionNoXMPP Service
PROSODY_SUPPORT_CONTACTSupport JID advertised in service discoveryNosupport@ + primary XMPP domain (same rule as PROSODY_DOMAIN / XMPP_DOMAIN)
PROSODY_SUPPORT_CONTACT_NICKSupport contact display nickNoSupport

​
Performance tuning (Lua GC)

Used only by prosody.cfg.lua (not listed in .env.example).
VariableDescriptionRequiredDefault (if unset)
LUA_GC_STEP_SIZELua garbage collector step sizeNo13
LUA_GC_PAUSELua GC pause parameterNo110
LUA_GC_SPEEDLua GC speed parameterNo200
LUA_GC_THRESHOLDLua GC threshold parameterNo120

​
PubSub feeds

VariableDescriptionRequiredDefault
PROSODY_FEED_URLAtom/RSS feed URL for PubSubNohttps://allthingslinux.org/feed

​
Bridge Service (Discord↔IRC↔XMPP relay)

Warning: BRIDGE_DISCORD_TOKEN is a full Discord bot credential — never commit. BRIDGE_PORTAL_TOKEN must equal the Portal’s BRIDGE_SERVICE_TOKEN when identity lookup is enabled.

​
Discord and Portal

VariableDescriptionDefault (.env.example)
BRIDGE_DISCORD_TOKENDiscord bot token(empty; set to run bridge)
BRIDGE_DISCORD_CHANNEL_IDChannel to bridge(empty)
BRIDGE_PORTAL_BASE_URLPortal origin (e.g. https://portal.example.com)(empty) — set in prod with Portal
BRIDGE_PORTAL_TOKENShared secret for /api/bridge/identity(empty)

​
XMPP component

VariableDescriptionDefault (.env.example)
BRIDGE_XMPP_COMPONENT_JIDComponent JIDbridge.xmpp.localhost
BRIDGE_XMPP_COMPONENT_SECRETComponent secret (match Prosody)change_me_xmpp_component_secret
BRIDGE_XMPP_COMPONENT_SERVERProsody hostname in Docker networkatl-xmpp-server
BRIDGE_XMPP_COMPONENT_PORTComponent listener port5347

​
IRC

VariableDescriptionDefault (.env.example)
BRIDGE_IRC_NICKBridge bot nickbridge
BRIDGE_IRC_OPER_PASSWORDOper password for bridge (if used)(empty in example)
IRC_BRIDGE_SERVERIRC server hostname in Docker networkatl-irc-server
BRIDGE_IRC_TLS_VERIFYVerify IRC TLS from bridgefalse (enable true with real certs)

​
Relay, redaction, and media

VariableDescriptionDefault (.env.example)
BRIDGE_RELAYMSG_CLEAN_NICKSCleaner RELAYMSG nicks (UnrealIRCd require-separator no)true
BRIDGE_IRC_REDACT_ENABLEDEnable IRC-side redaction handlingfalse
XMPP_AVATAR_BASE_URLInternal HTTP base for avatar checkshttp://atl-xmpp-server:5280
XMPP_AVATAR_PUBLIC_URLOptional public base for avatar URLs(empty)
XMPP_UPLOAD_FETCH_URLInternal base for upload fetch / Discord mediahttp://atl-xmpp-server:5280

​
Dev-only (no Portal)

Commented in .env.dev.example: BRIDGE_DEV_IRC_PUPPETS, BRIDGE_DEV_IRC_NICK_MAP — per-user IRC connections for local testing.
VariableDescriptionDefault
IRC_PUPPET_IDLE_TIMEOUT_HOURSDisconnect idle IRC puppet connections after this many hours24

​
Env overrides vs config.yaml

These environment variables override the corresponding fields in the bridge’s YAML config when set (see apps/bridge/src/bridge/config/schema.py): BRIDGE_IRC_REDACT_ENABLED, BRIDGE_RELAYMSG_CLEAN_NICKS, BRIDGE_IRC_TLS_VERIFY.

​
Logging

VariableDescriptionDefault
LOG_LEVELDEBUG, INFO, WARNING, ERRORINFO (.env.example); DEBUG in .env.dev.example

​
Web frontend (apps/web, Next.js)

VariableDescriptionDefault (.env.example)
NEXT_PUBLIC_IRC_WS_URLBrowser → IRC WebSocketwss://irc.localhost/ws
NEXT_PUBLIC_XMPP_BOSH_URLBrowser → XMPP BOSH (/http-bind on Prosody HTTP)https://xmpp.localhost:5281/http-bind (TLS via atl-xmpp-nginx; use http://localhost:5280/http-bind for plain HTTP to Prosody, e.g. just web dev)
XMPP WebSocket (RFC 7395) is served at path /xmpp-websocket on Prosody’s HTTP stack. With the dockerized nginx sidecar, use wss://<XMPP_DOMAIN>:5281/xmpp-websocket (or wss://…/ws, which nginx proxies to the same upstream). Do not confuse with BOSH at /http-bind. NEXT_PUBLIC_* values are baked in at build time for the web app — set them before pnpm build / image build for your domain.

​
Fluux messenger (infra/compose/fluux-messenger.yaml)

VariableDescriptionDefault (.env.example)
FLUUX_VERSIONFluux image / ref tagv0.13.3
FLUUX_DOMAINPublic vhost for the messengerwebxmpp.atl.chat
FLUUX_CERT_DOMAINCert / TLS identity helperatl.chat
FLUUX_MESSENGER_PORTHTTP port8091
FLUUX_MESSENGER_HTTPS_PORTHTTPS port8443
XMPP_DOMAINProsody host header for Fluux’s /ws → Prosody proxySame as XMPP_DOMAIN / JID domain (e.g. xmpp.localhost)
Fluux’s default URLs use port 443 (https://<jid-domain>/.well-known/…, wss://<jid-domain>/ws). atl-xmpp-nginx publishes 127.0.0.1:443 → :443 (same TLS as 5281) so those defaults work. If you cannot bind 127.0.0.1:443, drop that mapping and set Server (optional) to wss://<XMPP_DOMAIN>:5281/ws or wss://localhost:8443/ws (Fluux-side proxy after rebuild).

​
Docs (Cloudflare Workers via Alchemy)

VariableDescriptionRequiredDefault
ALCHEMY_PASSWORDPassword used by Alchemy to encrypt deployment state secretsYeschange-me
Warning: ALCHEMY_PASSWORD encrypts secrets in the deployment state. Use a strong, unique value and do not share it. Required only when running pnpm run deploy or pnpm run destroy from apps/docs.

​
Optional compose-only variables

Listed as comments in .env.example when they apply only if you enable a fragment or override:
VariablePurpose
IRC_SERVICES_SERVEROverride UnrealIRCd → Atheme link hostname
IRC_ENABLE_GEOIP_CLASSICGeoIP classic DB download at UnrealIRCd startup
WEBPANEL_PORTHost port for WebPanel (infra/compose/irc.yaml)
XMPP_WEBCHAT_URLPassed into Prosody for MUC webchat discovery
SSL_DOMAINCert-manager helper (infra/compose/cert-manager.yaml)
OBSIDIANIRC_*ObsidianIRC build args (see ObsidianIRC)

​
Portal integration (external ATL Portal)

The Portal app reads these from its own apps/portal/.env (see Portal docs/ENV_VARS.md). They are not substituted by prepare-config.sh in atl.chat; document them here so operators can align URLs and secrets with this stack. Typical values when Portal talks to Docker service hostnames (from Portal’s container network) vs public hostnames (from a host-run Portal) differ — use the hostname Portal can actually reach.
VariableRole
IRC_ATHEME_JSONRPC_URLAtheme JSON-RPC, e.g. http://atl-irc-server:8081/jsonrpc
IRC_UNREAL_JSONRPC_URLUnrealIRCd JSON-RPC HTTPS URL
IRC_UNREAL_RPC_USER / IRC_UNREAL_RPC_PASSWORDMatch WEBPANEL_RPC_*
PROSODY_REST_URLProsody admin API base — include path, e.g. http://atl-xmpp-server:5280/admin_api
PROSODY_REST_TOKENBearer from just prosody-token (preferred)
PROSODY_REST_USERNAME / PROSODY_REST_PASSWORDLegacy HTTP Basic for admin API — avoid if Bearer is configured
IRC_SERVER / IRC_PORTClient-style IRC connection target
Warning: Treat RPC and REST tokens as admin credentials; rotate defaults before production.

​
.env.dev overlay (just dev)

Compose loads .env then .env.dev. The committed .env.example is already localhost-oriented; .env.dev.example reiterates dev-safe TLS and adds bridge/docs-friendly defaults.

​
Variables set in .env.dev.example (non-commented)

VariableTypical purpose
ATL_CHAT_IP, ATL_GATEWAY_IP127.0.0.1 — local bind
IRC_DOMAIN, XMPP_DOMAIN, PROSODY_DOMAIN*.localhost hostnames
IRC_SSL_CERT_PATH, IRC_SSL_KEY_PATHPaths for dev certs
IRC_TLS_VERIFY, IRC_LOUNGE_REJECT_UNAUTHORIZED, IRC_WEBSOCKET_USE_TLS, BRIDGE_IRC_TLS_VERIFYDev TLS behaviour
PROSODY_ALLOW_PLACEHOLDER_KEY, PROSODY_HTTPS_VIA_PROXYLocal Prosody convenience
PROSODY_UPLOAD_EXTERNAL_URL, PROSODY_HTTP_EXTERNAL_URL, PROSODY_PROXY_ADDRESS, PROSODY_SSL_KEY, PROSODY_SSL_CERTURLs and cert paths for dev
PROSODY_C2S_REQUIRE_ENCRYPTION, PROSODY_S2S_REQUIRE_ENCRYPTION, PROSODY_S2S_SECURE_AUTH, PROSODY_ALLOW_UNENCRYPTED_PLAIN_AUTHRelaxed crypto for self-signed / plain
BRIDGE_XMPP_COMPONENT_JID, BRIDGE_PORTAL_BASE_URL, BRIDGE_RELAYMSG_CLEAN_NICKS, LOG_LEVELBridge: local JID, empty Portal URL, verbose logs
XMPP_AVATAR_BASE_URL, XMPP_UPLOAD_FETCH_URLDocker-internal Prosody HTTP for bridge
NEXT_PUBLIC_IRC_WS_URL, NEXT_PUBLIC_XMPP_BOSH_URLLocal web app endpoints

​
Commented examples in .env.dev.example

Uncomment and fill when needed:
VariablePurpose
BRIDGE_PORTAL_BASE_URL, BRIDGE_PORTAL_TOKENPortal on host (e.g. http://host.docker.internal:3000) — token must match Portal BRIDGE_SERVICE_TOKEN
PROSODY_REST_URL, PROSODY_REST_TOKENPortal-driven XMPP provisioning (just prosody-token)
BRIDGE_DEV_IRC_PUPPETS, BRIDGE_DEV_IRC_NICK_MAPDev IRC puppets without Portal
  • Ports Reference — complete port registry with all service ports
  • API Reference — Portal API and UnrealIRCd JSON-RPC endpoints
  • Glossary — definitions of project-specific terms and acronyms
  • FAQ — frequently asked questions about atl.chat
  • Security — secret generation and credential rotation for sensitive variables
  • Deployment — production deployment using these variables