The Lounge

Modern self-hosted web IRC client with always-online connectivity

The Lounge IRC Client

The Lounge is a modern, responsive, self-hosted web IRC client that runs continuously on your QuickBox server. Unlike traditional IRC clients, The Lounge provides a web-based interface accessible from any device with a browser, maintaining persistent IRC connections even when you’re offline. Perfect for users who want IRC access without installing desktop applications.

What is The Lounge?

The Lounge is a web-based IRC client that combines the convenience of modern web applications with the power of persistent IRC connections. Running on your QuickBox server, The Lounge maintains your IRC sessions 24/7, storing message history and keeping you connected even when your browser is closed.

Installation

Prerequisites

Before installing The Lounge, ensure your environment meets these requirements:

Install The Lounge

Install The Lounge for a specific user:

qb install thelounge -u username

Install beta version:

qb install thelounge -u username --beta

Automatic Installation Process

QuickBox performs comprehensive setup automatically:

1. 🔧 Environment Setup - Installs NVM, Node.js 18.20.0, npm 10.5.0, and Python 3.11
2. 📦 Virtual Environments - Creates isolated Python and Node.js environments
3. 🏗️ Build Process - Downloads, compiles, and builds The Lounge from source
4. ⚙️ Configuration - Generates config files with reverse proxy and SSL settings
5. 👤 User Account - Creates The Lounge account using your QuickBox password
6. 🔒 Service Setup - Configures systemd service with security sandboxing
7. 🌐 Nginx Integration - Sets up reverse proxy with WebSocket support
8. 💾 Automatic Backup - Creates initial configuration backup

CLI Commands

Basic Operations

Usage Examples

Install stable version:

qb install thelounge -u myuser

Install beta version for testing:

qb install thelounge -u myuser --beta

Update to latest version:

qb update thelounge -u myuser

Reinstall (fix corrupted installation while preserving data):

qb reinstall thelounge -u myuser

Remove The Lounge:

qb remove thelounge -u myuser

Accessing The Lounge

Web Interface Access

After installation, access The Lounge through your QuickBox dashboard or directly via URL:

Primary Access Methods:

Login Credentials:

• Username: Your QuickBox username
• Password: Your QuickBox password (automatically configured)

First-Time Setup

Step 1: Access The Lounge

Navigate to https://yourserver.com/thelounge/ and log in with your QuickBox credentials.

Step 2: Add IRC Network

1. Click the ”+” button or “Add Network” in the sidebar
2. Configure your IRC network:

Network Name:     Libera.Chat (or custom name)
Server:           irc.libera.chat
Port:             6697
Enable TLS/SSL:   ✓ (recommended)
Nickname:         your_nickname
Username:         your_username
Real Name:        Your Real Name

3. Click “Connect” to establish connection

Step 3: Join Channels

• Type /join #channel in the input box
• Or click a channel name if auto-join is configured
• Messages appear in real-time with persistent history

Common IRC Networks:

Configuration

Default Settings

The Lounge is configured with optimal defaults for QuickBox integration:

Configuration File

The Lounge’s configuration is stored in /home/username/.config/TheLounge/config.js:

// QuickBox automatically configures these settings:
host: "127.0.0.1",           // Listen on localhost only
port: 9000,                  // Internal port (proxied via nginx)
reverseProxy: true,          // Enable reverse proxy support
baseUrl: "/uploads",         // File upload base URL
public: false,               // Require authentication
prefetch: true,              // Preview URLs in messages
prefetchStorage: true,       // Store previews
fileUpload: true,            // Enable file uploads
maxHistory: 10000,           // Message history limit per channel

Advanced Configuration

Customize message history limit:

# Edit config file
nano /home/username/.config/TheLounge/config.js
 
# Find and modify:
maxHistory: 10000,  // Increase for more history
 
# Restart service
systemctl restart thelounge@username

Enable/disable file uploads:

# Edit config file
nano /home/username/.config/TheLounge/config.js
 
# Find and modify:
fileUpload: true,  // Set to false to disable
 
# Restart service
systemctl restart thelounge@username

Change themes:

1. Access The Lounge web interface
2. Click Settings (gear icon)
3. Select Appearance tab
4. Choose from available themes
5. Changes save automatically

Service Management

The Lounge runs as a per-user systemd service with security sandboxing:

Basic Service Commands

Check service status:

systemctl status thelounge@username

Start service:

systemctl start thelounge@username

Stop service:

systemctl stop thelounge@username

Restart service:

systemctl restart thelounge@username

Enable service (start on boot):

systemctl enable thelounge@username

Disable service:

systemctl disable thelounge@username

Viewing Logs

View service logs:

journalctl -u thelounge@username -f

View application logs:

tail -f /home/username/.config/TheLounge/logs/*.log

Check last 100 log entries:

journalctl -u thelounge@username -n 100

Service Configuration

The systemd service includes security features:

# /etc/systemd/system/thelounge@username.service
[Service]
User=username
Group=username
Type=simple
 
# Environment variables
Environment="TMPDIR=/home/username/tmp/TheLounge"
Environment="THELOUNGE_HOME=/home/username/.config/TheLounge"
 
# Security hardening
ProtectSystem=yes
NoNewPrivileges=yes
PrivateTmp=yes

Features

Core Features

Advanced Features

Message Formatting:

• Markdown support for bold, italic, and code
• IRC color codes and formatting
• Emoji support with autocomplete
• Code block syntax highlighting

File Sharing:

• Drag-and-drop file uploads
• Image paste from clipboard
• Automatic thumbnail generation
• Direct file links for sharing

User Experience:

• Infinite scroll for message history
• Unread message indicators
• Desktop notifications via browser
• Mobile-optimized touch interface

When to Use The Lounge

Troubleshooting

Common Issues & Solutions

Service Won’t Start

Symptoms: systemctl start thelounge@username fails or service immediately stops

Solutions:

1. Check service status: systemctl status thelounge@username
2. Review logs: journalctl -u thelounge@username -n 50
3. Verify Node.js environment: ls -la /opt/username/lib/nodejs/TheLounge/.venv/
4. Check permissions: ls -la /home/username/.config/TheLounge/
5. Reinstall if corrupted: qb reinstall thelounge -u username

Cannot Access Web Interface

Symptoms: Browser shows connection refused or timeout errors

Solutions:

1. Verify service is running: systemctl is-active thelounge@username
2. Check port is listening: ss -tlnp | grep 9000
3. Test nginx proxy: nginx -t && systemctl reload nginx
4. Verify nginx config: cat /etc/nginx/software/thelounge.conf
5. Check firewall rules: ufw status

Login Fails

Symptoms: Incorrect username or password error

Solutions:

1. Verify username matches QuickBox account
2. Reset password via The Lounge CLI:

export THELOUNGE_HOME="/home/username/.config/TheLounge"
/usr/bin/thelounge reset username

3. Check user file exists: ls -la /home/username/.config/TheLounge/users/
4. Reinstall to regenerate user: qb reinstall thelounge -u username

IRC Connection Issues

Symptoms: Cannot connect to IRC networks, timeout errors

Solutions:

1. Verify network settings in The Lounge interface
2. Check server address and port are correct
3. Enable SSL/TLS for secure connections (port 6697)
4. Test connection manually: telnet irc.libera.chat 6697
5. Check firewall allows outbound IRC connections

File Uploads Not Working

Symptoms: Upload fails or files not accessible

Solutions:

1. Verify upload directory exists: ls -la /home/username/.config/TheLounge/uploads/
2. Check permissions: chown username:username -R /home/username/.config/TheLounge/uploads/
3. Verify nginx config has upload path: cat /etc/nginx/software/thelounge.conf
4. Check fileUpload enabled in config.js
5. Restart nginx: systemctl reload nginx

Best Practices

Security Recommendations

• Access Control: Always use strong passwords and enable HTTPS
• Network Security: Use SSL/TLS for IRC connections to prevent eavesdropping
• File Uploads: Regularly review uploads directory for malicious files
• Updates: Keep The Lounge updated to receive security patches
• Monitoring: Monitor systemd logs for suspicious authentication attempts

Additional Resources

Related Applications

The Lounge works well alongside these QuickBox Pro communication tools:

QuickBox Integration

The Lounge integrates seamlessly with QuickBox Pro:

• Dashboard Widget: Monitor The Lounge status from QuickBox dashboard
• Single Sign-On: Uses QuickBox credentials for authentication
• Automatic Backups: Configuration backed up during updates
• Service Monitoring: Health checks and automatic restart on failure
• Database Tracking: Version and port information stored in QuickBox database
• Nginx Integration: Automatic reverse proxy configuration with SSL support
• Per-User Isolation: Each user gets independent The Lounge instance

Support & Community

Need help with The Lounge? The QuickBox community is here to help!

Getting Help