RamNode logo
    Sign UpLogin
    Deployment Guides
    IRC
    Docker

    Deploy The Lounge IRC Client on a VPS

    Always-on, self-hosted IRC in your browser. Stays connected 24/7, keeps full message history, and works from any device.

    At a Glance

    ProjectThe Lounge
    LicenseMIT
    Recommended PlanAny RamNode VPS (1 GB RAM is sufficient)
    OSUbuntu 22.04 LTS
    Default Port9000 (proxied to 443 via Nginx)
    DeploymentDocker + Docker Compose
    Estimated Setup Time10–15 minutes

    Prerequisites

    • A RamNode VPS running Ubuntu 22.04 LTS (any plan works; 1 GB RAM is more than sufficient)
    • A non-root sudo user
    • A domain or subdomain pointed at your VPS IP (e.g., irc.yourdomain.com)
    • Ports 80 and 443 open in your firewall
    1

    Update Your System

    Update and upgrade
    sudo apt update && sudo apt upgrade -y
    2

    Install Docker

    The Lounge's official Docker image is the easiest path to a clean, upgradeable deployment.

    Install Docker
    sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

    Add your user to the docker group:

    Add user to docker group
    sudo usermod -aG docker $USER
newgrp docker
    Verify installation
    docker --version
    3

    Create the Data Directory

    The Lounge stores all configuration, user accounts, and message logs in a single directory. Set ownership to UID 1000, which the official image uses internally:

    Create data directory
    sudo mkdir -p /opt/thelounge
sudo chown -R 1000:1000 /opt/thelounge
    4

    Create the Docker Compose File

    Create compose file
    nano /opt/thelounge/docker-compose.yml
    docker-compose.yml
    version: "3.8"

services:
  thelounge:
    image: ghcr.io/thelounge/thelounge:latest
    container_name: thelounge
    restart: unless-stopped
    ports:
      - "127.0.0.1:9000:9000"
    volumes:
      - /opt/thelounge/data:/var/opt/thelounge
    environment:
      - THELOUNGE_HOME=/var/opt/thelounge

    Note: Port 9000 is bound to localhost only. Nginx will handle SSL termination and public access.

    5

    Start the Container

    Start The Lounge
    cd /opt/thelounge
docker compose up -d

    Check that it is running:

    Check status
    docker compose ps
docker compose logs -f

    You should see output indicating The Lounge is listening on port 9000. Press Ctrl+C to exit the log stream.

    6

    Create Your First User

    The Lounge uses a CLI for user management:

    Create user
    docker exec -it thelounge thelounge add yourusername

    You will be prompted to set a password. To list existing users:

    List users
    docker exec -it thelounge thelounge list
    7

    Install and Configure Nginx

    Install Nginx
    sudo apt install -y nginx

    Create a server block (replace irc.yourdomain.com with your domain):

    /etc/nginx/sites-available/thelounge
    server {
    listen 80;
    listen [::]:80;
    server_name irc.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;

        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

    Important: The Upgrade and Connection headers are required for WebSocket support. The proxy_read_timeout prevents idle WebSocket disconnects.

    Enable site and reload
    sudo ln -s /etc/nginx/sites-available/thelounge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
    8

    Obtain an SSL Certificate

    Install Certbot
    sudo apt install -y certbot python3-certbot-nginx
    Request certificate
    sudo certbot --nginx -d irc.yourdomain.com

    Certbot will automatically update your Nginx config to handle HTTPS. When prompted, choose to redirect HTTP to HTTPS.

    Verify auto-renewal
    sudo certbot renew --dry-run
    9

    Configure UFW

    Firewall rules
    sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

    You do not need to open port 9000 externally since Nginx handles all incoming traffic.

    10

    Log In and Connect to IRC

    Open your browser and navigate to https://irc.yourdomain.com. Log in with the credentials from Step 6.

    On first login, The Lounge will prompt you to add a network. Example settings for Libera.Chat:

    Serverirc.libera.chat
    Port6697
    TLSEnabled
    NickYour preferred IRC identity

    The Lounge will hold this connection open indefinitely — even after you close the browser tab.

    Managing The Lounge

    Upgrade to a New Version

    Upgrade
    cd /opt/thelounge
docker compose pull
docker compose up -d

    Configuration and message logs in /opt/thelounge/data are preserved across upgrades.

    Add Additional Users

    Add user
    docker exec -it thelounge thelounge add seconduser

    By default, The Lounge runs in private mode — only accounts you create via the CLI can log in.

    Reset a Password

    Reset password
    docker exec -it thelounge thelounge reset yourusername

    Remove a User

    Remove user
    docker exec -it thelounge thelounge remove yourusername

    View Logs

    View logs
    docker compose -f /opt/thelounge/docker-compose.yml logs -f

    Optional Configuration

    Push Notifications

    The Lounge supports browser push notifications for highlights and private messages. This works out of the box over HTTPS — go to Settings → Notifications in the web client.

    VAPID Keys for Self-Hosted Push

    For full Web Push support independent of a third-party service, generate VAPID keys:

    Generate VAPID keys
    docker exec -it thelounge thelounge genconfig

    Paste the output values into /opt/thelounge/data/config.js under the vapid section. Restart after changes:

    Restart container
    docker compose -f /opt/thelounge/docker-compose.yml restart

    Troubleshooting

    Container exits immediately

    Check logs and verify directory ownership:

    Check logs and permissions
    docker compose logs thelounge
ls -la /opt/thelounge/data
sudo chown -R 1000:1000 /opt/thelounge/data

    WebSocket connection fails

    Ensure your Nginx config includes the Upgrade and Connection proxy headers and the proxy_read_timeout directive. A default 60-second timeout will cause WebSocket connections to drop.

    Cannot connect to IRC network

    Some IRC networks require identd or a valid reverse DNS entry. Set custom rDNS in the RamNode Client Portal. Libera.Chat and most networks support SASL authentication, which The Lounge supports natively.

    Certbot fails on port 80

    Make sure Nginx is running and UFW allows port 80:

    Check status
    sudo systemctl status nginx
sudo ufw status
    More Deployment Guides•View Cloud VPS Plans