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 guide walks you through cloning the repo, configuring environment variables, and starting all services with a single command.

​
Clone and install

  1. Clone the repository and install Node.js dependencies: 
    git clone https://github.com/allthingslinux/atl.chat.git
cd atl.chat
pnpm install
  2. Install Python dependencies with uv: 
    # Install Python tooling (pytest, pre-commit, etc.)
uv sync

​
Environment setup

Copy the example env files and customise values for local development: 
# Main environment file
cp .env.example .env

# Dev overlay (overrides domains to localhost)
cp .env.dev.example .env.dev
Key variables to set for local development:
VariableDescription
IRC_DOMAINIRC server hostname (defaults to irc.localhost in .env.dev)
PROSODY_DOMAINXMPP server domain (defaults to xmpp.localhost in .env.dev)
DISCORD_TOKENDiscord bot token for the bridge (optional for IRC/XMPP-only testing)
See the full Environment Variables reference for all available options.

​
First-time initialisation

Run the init recipe to create data directories, generate self-signed TLS certificates, and substitute config templates: 
just init
This runs scripts/init.sh, which:
  • Creates all data/ subdirectories for persistent storage
  • Generates self-signed TLS certificates for local development
  • Runs envsubst on config templates to produce final config files

​
Starting the stack

just dev
This starts all Docker Compose services with the dev profile. Verify the stack is running: 
just status

​
Starting the web app

The Next.js web app runs outside Docker as a local Node process: 
cd apps/web
NEXT_PUBLIC_IRC_WS_URL="ws://localhost:8000" \
NEXT_PUBLIC_XMPP_BOSH_URL="http://localhost:5280/http-bind" \
pnpm dev
The web interface is available at http://localhost:3000.

​
Verification checklist

After just dev completes, verify each service is running:
  1. Check container status: 
    just status
  2. Test IRC connectivity (TLS on port 6697): 
    openssl s_client -connect localhost:6697 -servername irc.localhost </dev/null 2>/dev/null | head -5
  3. Test XMPP connectivity (C2S on port 5222): 
    curl -s http://localhost:5280/http-bind
  4. Test The Lounge web client (port 9000): 
    curl -s -o /dev/null -w "%{http_code}" http://localhost:9000
# Expected: 200
  5. Test ObsidianIRC (port 8090): 
    curl -s -o /dev/null -w "%{http_code}" http://localhost:8090
# Expected: 200
  6. Test WebPanel (port 8080): 
    curl -s -o /dev/null -w "%{http_code}" http://localhost:8080
# Expected: 200

​
Useful just recipes

RecipeDescription
just devStart all services with dev profile
just downStop the dev stack
just logs [service]Follow logs (optionally for a specific service)
just statusShow container status
just lintRun all pre-commit hooks
just testRun unit tests
just test-allRun all tests including bridge tests

​
Common first-run issues

​
Docker daemon not running

If you see “Cannot connect to the Docker daemon”, start Docker first: 
sudo dockerd &>/tmp/dockerd.log &

​
Port already in use

If a port is already bound, identify the process and stop it: 
# Find what is using port 6697
sudo lsof -i :6697

​
CLOUDFLARE_DNS_API_TOKEN warning

Docker Compose emits a warning about this unset variable. You can safely ignore it in development — the cert-manager service is not needed locally.

​
pnpm install build scripts warning

You may see warnings about blocked build scripts for esbuild, sharp, or workerd. These packages have fallback binaries and the warning is non-blocking.

​
pre-commit hooks fail to install

If core.hooksPath is set by your environment, unset it first: 
git config --unset-all core.hooksPath
uv run pre-commit install

​
The Lounge shows login page but no users exist

The Lounge runs in private mode. You need to create a user before you can log in: 
just lounge add <username>

​
ObsidianIRC: “Firefox can’t establish a connection” to wss://127.0.0.1:8000

In dev, ObsidianIRC connects to the IRC WebSocket over TLS with a self-signed certificate. Firefox blocks WebSocket connections to untrusted certs without prompting. Add a certificate exception first:
  1. Open a new tab and go to https://127.0.0.1:8000/
  2. When Firefox shows “Connection Not Secure”, click Advanced
  3. Click Accept the Risk and Continue
  4. Reload ObsidianIRC at http://localhost:8090 and connect again