OpenLiteSpeed is configured mainly through its WebAdmin console, a web GUI on port 7080. Its model is different from Apache or Nginx: listeners own the ports, virtual hosts hold the site settings, and mappings join the two by domain. This guide walks through adding a site end to end.
Before you start
- OpenLiteSpeed installed: see install OpenLiteSpeed on Ubuntu or AlmaLinux.
- A domain with its A record pointing to the server.
- Port 7080 allowed only from your IP (or reach it through an SSH tunnel).
Log in to WebAdmin
- Set or reset the admin password:
sudo /usr/local/lsws/admin/misc/admpass.sh - Open
https://SERVER_IP:7080and accept the self-signed certificate warning.
How the pieces fit
| Object | Holds |
|---|---|
| Server Configuration | Global tuning, PHP external apps, modules, security |
| Listeners | IP and port (e.g. *:80, *:443), SSL for that port |
| Virtual Hosts | Document root, index files, logs, rewrite, per-site SSL, contexts |
| Virtual Host Mappings | Which domains on a listener go to which vhost |
Create the document root
sudo mkdir -p /var/www/example.com/{html,logs}
sudo chown -R nobody:nogroup /var/www/example.comOn AlmaLinux the group is nobody. Use a dedicated user with suEXEC if you host several owners.
Add the virtual host
- Go to Virtual Hosts → Add.
- Name:
example.com; Virtual Host Root:/var/www/example.com/; Config File:$SERVER_ROOT/conf/vhosts/$VH_NAME/vhconf.conf. Click the create link when it says the file does not exist. - Set Enable Scripts/ExtApps and Restrained to Yes. Save.
- Open the vhost → General: Document Root
$VH_ROOT/html/, Domain Nameexample.com, Domain Aliaseswww.example.com; Index Filesindex.php, index.html. - Log tab: point error and access logs to
$VH_ROOT/logs/.
Enable rewrites and .htaccess
In the vhost → Rewrite: Enable Rewrite = Yes, Auto Load from .htaccess = Yes. OpenLiteSpeed reads only the rewrite rules from .htaccess, and only at startup, so do a graceful restart after editing it.
Map the vhost to listeners
- Listeners → Default (port 80) → Virtual Host Mappings → Add: Virtual Host
example.com, Domainsexample.com, www.example.com. - Create a listener for HTTPS if none exists: Listeners → Add, Name
SSL, IPANY, Port443, Secure = Yes. Add the same mapping.
Add an SSL certificate
- Issue a certificate with the webroot method:
sudo certbot certonly --webroot -w /var/www/example.com/html -d example.com -d www.example.com - In the vhost → SSL: Private Key File
/etc/letsencrypt/live/example.com/privkey.pem, Certificate File/etc/letsencrypt/live/example.com/fullchain.pem, Chained Certificate Yes. - The 443 listener also needs a default certificate in its own SSL tab; per-vhost certificates are selected by SNI.
- Add a Certbot deploy hook that runs
/usr/local/lsws/bin/lswsctrl restartso renewals load.
Choose the PHP version
PHP runs as an LSAPI external app (lsphp). Under Server Configuration → External App each installed lsphp version appears; a matching Script Handler maps .php to it. To use a different version for one site, add a script handler in that vhost's Script Handler tab. Background: LSAPI explained.
Apply changes
Click Graceful Restart (top right). It reloads config without dropping connections. From the shell: sudo /usr/local/lsws/bin/lswsctrl restart.
Troubleshooting
- Default "Congratulations" page shows: mapping missing on that listener, or the domain spelled differently.
- 404 on pretty URLs: rewrite not enabled or no restart after editing .htaccess.
- Wrong certificate on HTTPS: vhost SSL not set, so the listener's default certificate was used.
FAQ: OpenLiteSpeed WebAdmin
Can I edit config files instead of the GUI?
Yes, files are in /usr/local/lsws/conf/, but the GUI rewrites them; don't mix both at once.
Should port 7080 be public?
No. Restrict it by IP or use an SSH tunnel.
Does a graceful restart drop visitors?
No. New processes take over while old ones finish their requests.