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.

This page answers the most common questions about atl.chat — what it is, how to connect, how to contribute, and how to handle everyday operational tasks.

​
General

​
What is atl.chat?

atl.chat is the unified chat infrastructure for the All Things Linux community. It provides IRC (via UnrealIRCd and Atheme), XMPP (via Prosody), a Discord bridge, and web-based clients — all running as a single Docker Compose stack in one monorepo.

​
How do the services relate to each other?

UnrealIRCd handles IRC connections and Atheme provides nickname/channel registration on top of it (they share a Docker network namespace). Prosody runs the XMPP side independently. The Bridge relays messages between Discord, IRC, and XMPP so users on any platform see the same conversations. The Lounge and ObsidianIRC are web IRC clients that connect to UnrealIRCd, and the WebPanel gives operators a browser-based admin interface via UnrealIRCd’s JSON-RPC API.

​
Is atl.chat open source?

Yes. The entire monorepo — server configs, bridge code, web apps, documentation, and infrastructure — is open source. You can fork it, run your own instance, or contribute back via pull requests.

​
Connecting

​
How do I connect to IRC?

You have several options:
  1. Desktop IRC client (HexChat, irssi, WeeChat) — connect to irc.atl.tools on port 6697 with TLS enabled.
  2. The Lounge — open the web client in your browser (port 9000 in dev, or the public URL in production). You need an account created by an operator (just lounge add).
  3. ObsidianIRC — a modern web client (port 8090 in dev). Pre-configured for ATL IRC with auto-join enabled.
See the IRC overview for full connection details.

​
How do I connect to XMPP?

Use any XMPP client (Conversations on Android, Gajim on desktop, Moxxy on iOS) and connect to the Prosody server on port 5222 with TLS. Browser-based access is available via BOSH (port 5280) or WebSocket. See the XMPP overview for details.

​
Can I use Discord instead?

Yes. The Bridge relays messages between Discord, IRC, and XMPP channels automatically. You chat on Discord as usual and your messages appear on IRC/XMPP (and vice versa). No extra setup is needed on the user side.

​
How do I register my IRC nickname?

After connecting, register with NickServ: 
/msg NickServ REGISTER <password> <email>
Then identify on future connections: 
/msg NickServ IDENTIFY <password>
Most modern clients support SASL authentication, which identifies you automatically at connect time. See the Atheme operations page for more NickServ commands.

​
Contributing

​
How do I contribute to atl.chat?

  1. Fork the repository and clone it locally.
  2. Follow the local development guide to get the stack running.
  3. Create a feature branch, make your changes, and open a pull request.
The project uses Conventional Commits, pre-commit hooks (just lint), and automated tests (just test). See the full contributing guide for branch naming, code style, and review expectations.

​
What languages and tools does the project use?

AreaLanguage / Tool
IRC server configUnrealIRCd config format, Lua scripts
IRC servicesAtheme (C, configured via template)
XMPP serverProsody (Lua configuration)
BridgePython
Web app and docsTypeScript, Next.js, MDX
InfrastructureDocker Compose, bash scripts, just
Lintingruff (Python), Biome (TypeScript), luacheck (Lua), shellcheck (bash)
See the contributing page for code style guides per language.

​
How do I run the tests?

# Unit tests (fast, no Docker needed)
uv run pytest tests/unit/

# Bridge tests (fast, no Docker needed)
uv run pytest apps/bridge/tests/

# All tests
just test-all
See the testing guide for the full test directory layout, fixtures, and CI integration.

​
Operations

​
How do I add a new user to The Lounge?

just lounge add <username>
You will be prompted for a password. The user can then log in to The Lounge web interface. See The Lounge operations for listing, resetting, and removing users.

​
How do I rotate secrets and passwords?

Generate new values for sensitive environment variables (anything containing PASSWORD, TOKEN, SECRET, or KEY in .env), then restart the affected services: 
# Generate a secure random value
openssl rand -base64 32

# After updating .env, restart the stack
just prod
See the security page for per-variable generation commands and the full credential rotation procedure.

​
How do I check if services are healthy?

Quick health checks for each service: 
# IRC — verify TLS connection
openssl s_client -connect localhost:6697 -servername irc.localhost </dev/null 2>/dev/null | head -5

# XMPP — check BOSH endpoint
curl -sf http://localhost:5280/http-bind

# The Lounge — HTTP health
curl -sf http://localhost:9000

# Container status
just status
See the monitoring page for comprehensive health checks, log inspection patterns, and alerting strategies.

​
How do I update or upgrade services?

  1. Back up persistent data (data/ directory) — see the backups guide.
  2. Pull the latest changes: git pull.
  3. Rebuild and restart: just build then just prod.
  4. Verify services are running: just status.
For TLS certificate renewal and post-renewal hooks (UnrealIRCd rehash, Prosody reload), see the SSL/TLS page.

​
Where do I find logs?

# Follow all service logs
just logs

# Follow a specific service
just logs unrealircd
just logs prosody
just logs bridge
Docker Compose logs are the primary source. In dev mode, Dozzle provides a browser-based log viewer. See monitoring for log inspection patterns and filtering tips.