BetterDesk/docs/setup/INSTALLATION_V1.4.0.md

🚀 BetterDesk Console v1.4.0 - Installation & Update Guide

📋 What's New in v1.4.0

🔐 Authentication System

• User login with username/password
• Session management (24-hour sessions)
• Password hashing with bcrypt
• Default admin account created automatically

👥 Role-Based Access Control

• Admin: Full access (manage users, devices, settings)
• Operator: Can ban/unban, edit devices, view audit log
• Viewer: Read-only access

🎨 New UI Features

• Sidebar navigation menu with glassmorphism design
• Responsive design for mobile/tablet
• User profile display in sidebar
• Better page organization

🔒 Security Improvements

• All API endpoints protected with authentication
• Audit logging for all operations
• XSS protection with MarkupSafe
• Session expiry and automatic cleanup
• CSRF protection ready (can be enabled)

---

🆕 New Installation

Quick Install (Recommended)

# Download and run installer
curl -O https://raw.githubusercontent.com/UNITRONIX/Rustdesk-FreeConsole/main/install-improved.sh
chmod +x install-improved.sh
sudo ./install-improved.sh

The installer will:

1. Install RustDesk HBBS/HBBR servers (if not present)
2. Install web console with authentication
3. Create database with auth tables
4. Generate default admin credentials
5. Configure systemd services

---

🔄 Updating from v1.3.0 or older

Automatic Update (Recommended)

# Download update script
cd /path/to/Rustdesk-FreeConsole
chmod +x update-to-v1.4.0.sh
sudo ./update-to-v1.4.0.sh

What the Update Script Does:

1. Detects current version automatically
2. Creates backup of:
   • Web console files
   • Database
   • Configuration
3. Installs new dependencies:
   • bcrypt (password hashing)
   • markupsafe (XSS protection)
4. Updates web files:
   • New auth.py module
   • Updated app.py with auth endpoints
   • New login.html template
   • Updated index.html with sidebar
   • New CSS and JavaScript files
5. Runs database migration:
   • Adds users table
   • Adds sessions table
   • Adds audit_log table
   • Creates default admin user
6. Restarts services
7. Shows admin credentials (if new)

Manual Update Steps

If you prefer manual update:

# 1. Backup
sudo cp -r /opt/BetterDeskConsole /opt/BetterDeskConsole.backup
sudo cp /opt/rustdesk/db_v2.sqlite3 /opt/rustdesk/db_v2.sqlite3.backup

# 2. Install dependencies
sudo pip3 install bcrypt markupsafe --break-system-packages

# 3. Copy new files
cd /path/to/Rustdesk-FreeConsole
sudo cp web/auth.py /opt/BetterDeskConsole/
sudo cp web/app.py /opt/BetterDeskConsole/
sudo cp web/templates/login.html /opt/BetterDeskConsole/templates/
sudo cp web/templates/index.html /opt/BetterDeskConsole/templates/
sudo cp web/static/style.css /opt/BetterDeskConsole/static/
sudo cp web/static/script.js /opt/BetterDeskConsole/static/

# 4. Run migration
sudo python3 migrations/v1.4.0_auth_system.py

# 5. Restart service
sudo systemctl restart betterdesk

---

🔑 First Login

After installation/update, you'll receive default admin credentials:

========================================
DEFAULT ADMIN CREDENTIALS:
========================================
Username: admin
Password: <randomly-generated-password>
========================================

⚠️ IMPORTANT:

1. Save these credentials in a secure location
2. Login immediately and change the password
3. Delete credentials file: sudo rm /opt/BetterDeskConsole/admin_credentials.txt

Accessing the Console

# Local access (on server)
http://localhost:5000

# Remote access (via SSH tunnel - RECOMMENDED)
ssh -L 8080:localhost:5000 user@your-server
# Then open: http://localhost:8080

---

👥 User Management

Creating Additional Users (Admin Only)

You can create additional users via Python console:

cd /opt/BetterDeskConsole/web
python3 -c "
from auth import create_user, ROLE_ADMIN, ROLE_OPERATOR, ROLE_VIEWER

# Create operator
create_user('operator1', 'SecurePassword123', ROLE_OPERATOR)

# Create viewer
create_user('viewer1', 'SecurePassword123', ROLE_VIEWER)

print('Users created successfully')
"

User Roles Explained

Role	Permissions
Admin	Full access: manage users, devices, settings, view audit log
Operator	Ban/unban devices, edit device info, view audit log
Viewer	Read-only: view devices and statistics

---

🔒 Security Best Practices

1. Change Default Password

1. Login with default credentials
2. Click your name in sidebar
3. Go to Settings
4. Click "Change Password"
5. Enter current password and new password

2. Use SSH Tunnel (Recommended)

Never expose port 5000 to the internet!

# From your local machine
ssh -L 8080:localhost:5000 user@your-server

# Keep this terminal open
# Access console at: http://localhost:8080

3. Firewall Configuration

# Block external access to console
sudo ufw deny 5000

# Allow only SSH
sudo ufw allow 22

# Allow RustDesk ports
sudo ufw allow 21115:21117/tcp
sudo ufw allow 21116/udp

4. Regular Backups

# Backup database
sudo cp /opt/rustdesk/db_v2.sqlite3 /backup/db_v2.sqlite3.$(date +%Y%m%d)

# Backup web console
sudo tar -czf /backup/betterdesk-$(date +%Y%m%d).tar.gz /opt/BetterDeskConsole

---

🐛 Troubleshooting

Login Issues

Problem: "Invalid username or password"

Solutions:

1. Check credentials file: sudo cat /opt/BetterDeskConsole/admin_credentials.txt
2. Reset admin password:

   cd /opt/BetterDeskConsole/web
   python3 -c "
   from auth import reset_password
   reset_password(1, 'NewPassword123')  # User ID 1 is admin
   print('Password reset successfully')
   "
   

Session Expired

Problem: Automatically logged out

Solution: Sessions expire after 24 hours. This is normal security behavior.

Migration Errors

Problem: Database migration fails

Solutions:

1. Check database permissions:

   ls -la /opt/rustdesk/db_v2.sqlite3
   sudo chown root:root /opt/rustdesk/db_v2.sqlite3
   

2. Restore from backup if needed:

   sudo cp /opt/rustdesk/db_v2.sqlite3.backup-pre-v1.4.0 /opt/rustdesk/db_v2.sqlite3
   

3. Try migration again:

   sudo python3 migrations/v1.4.0_auth_system.py
   

Service Won't Start

Check logs:

sudo journalctl -u betterdesk -n 50 --no-pager

Common issues:

• Missing dependencies: sudo pip3 install bcrypt markupsafe --break-system-packages
• Database locked: sudo systemctl restart rustdesksignal
• Port conflict: sudo netstat -tulpn | grep 5000

---

📊 Audit Log

View user actions:

# View audit log in database
sqlite3 /opt/rustdesk/db_v2.sqlite3 "
SELECT 
    u.username,
    a.action,
    a.device_id,
    a.timestamp,
    a.ip_address
FROM audit_log a
LEFT JOIN users u ON a.user_id = u.id
ORDER BY a.timestamp DESC
LIMIT 50;
"

---

🔄 Rollback to v1.3.0

If you need to rollback:

# Stop service
sudo systemctl stop betterdesk

# Restore backup
sudo rm -rf /opt/BetterDeskConsole
sudo cp -r /opt/BetterDeskConsole.backup /opt/BetterDeskConsole

# Restore database
sudo cp /opt/rustdesk/db_v2.sqlite3.backup /opt/rustdesk/db_v2.sqlite3

# Restart service
sudo systemctl start betterdesk

---

📞 Support

• GitHub Issues: https://github.com/UNITRONIX/Rustdesk-FreeConsole/issues
• Documentation: See docs/ folder
• Security Issues: Use GitHub Security Advisories (private reporting)

---

✅ Post-Installation Checklist

• Login with default credentials works
• Changed admin password
• Deleted credentials file
• Configured firewall (block port 5000 externally)
• Set up SSH tunnel for remote access
• Tested device list loading
• Tested ban/unban functionality
• Created backup of database
• Verified audit logging works

---

Last updated: 14 stycznia 2026
Version: 1.4.0