Manual Installation and Configuration Guide for OpenLiteSpeed Server on Ubuntu

Introduction

OpenLiteSpeed is an open-source, high-performance HTTP server known for being lightweight, fast, and supporting the proprietary LiteSpeed Cache engine (LSCache). This guide details the steps for manually installing and configuring OpenLiteSpeed on an Ubuntu system.

System Requirements and Preparation

This tutorial is based on Ubuntu 20.04 LTS or 22.04 LTS. Ensure you have root or sudo privileges.

First, update the system package list:

sudo apt update
sudo apt upgrade -y

Installing OpenLiteSpeed

Step 1: Add the OpenLiteSpeed Repository

OpenLiteSpeed provides an official APT repository for easy installation and updates.

sudo apt install software-properties-common apt-transport-https lsb-release ca-certificates
sudo wget -O /etc/apt/trusted.gpg.d/lst_repo.gpg https://rpms.litespeedtech.com/debian/lst_repo.gpg
sudo wget -O /etc/apt/sources.list.d/lst.list https://rpms.litespeedtech.com/debian/lst.list

Step 2: Install the OpenLiteSpeed Package

Update the repository information and install the core package:

sudo apt update
sudo apt install openlitespeed -y

After installation, the OpenLiteSpeed service starts automatically. Check its status with:

sudo systemctl status lshttpd

Basic Configuration

Step 3: Set the Administrator Password

OpenLiteSpeed provides a web-based admin interface. Before first access, set a password for the admin account.

sudo /usr/local/lsws/admin/misc/admpass.sh

Run this script and follow the prompts to enter your desired username and password.

Step 4: Access the Admin Panel

The OpenLiteSpeed admin interface runs on port 7080 by default. Access it in your browser at:

https://your_server_ip:7080

Log in using the username and password set in the previous step. Note: due to the self-signed certificate, your browser will show a security warning; you can temporarily choose "Continue" or "Advanced - Accept the risk and continue".

Step 5: Configure the Listener

The "Listener" section in the admin panel configures how the server responds to requests.

1. Click "Listener" in the left menu.
2. You will see a listener named "Default" listening on port 8088.
3. Click "View/Edit" to enter the default listener settings.
4. In the "General" tab, you can change the port from 8088 to the standard HTTP port 80 (or HTTPS port 443, which requires SSL certificate configuration).
5. In the "Virtual Host Mappings" section, ensure it maps to the "Example" virtual host.
6. Click the "Save" button in the top right, then click the "Restart" icon (or return to the homepage and click "Graceful Restart") to apply the changes.

Configuring Virtual Hosts and PHP

Step 6: Install the PHP Processor (LSAPI)

OpenLiteSpeed communicates with PHP via LiteSpeed SAPI (LSAPI). Install your required PHP version:

sudo apt install lsphp81 lsphp81-common lsphp81-curl lsphp81-mysql -y

(The above command installs PHP 8.1 and common extensions. You can replace `81` with `74`, `82`, etc., to install other versions.)

Step 7: Configure the Virtual Host to Use PHP

1. In the admin panel, go to "Server Configuration" -> "External App".
2. Click "Add", select type "LiteSpeed SAPI App".
3. Enter a name like `lsphp81`, and for the address use `uds://tmp/lshttpd/lsphp81.sock` (or `$SERVER_ROOT/fcgi-bin/lsphp81`).
4. For the command, enter `/usr/bin/lsphp81`.
5. Go to the "Script Handler" section, click "Add". Set suffix to `php` and the handler to the `lsphp81` app you just created.
6. Go to "Virtual Host" -> "Example" -> "General" -> "Script Handler Definition", and select the script handler set you created.
7. Save and restart the server.

Deploying a Website

Step 8: Upload Website Files

The default website root directory is located at:

/usr/local/lsws/Example/html/

You can upload your website files (e.g., WordPress files) to this directory, or create a new virtual host with a custom document root.

Step 9: Create a New Virtual Host (Optional)

1. In the admin panel, go to "Virtual Host", click the "Add" button.
2. Enter a virtual host name (e.g., `mywebsite`) and the document root path (e.g., `/var/www/mywebsite/public_html`).
3. In the "General" tab, configure index files (e.g., `index.php, index.html`).
4. In the "Script Handler" section, associate the previously created PHP processor.
5. Finally, edit the "Default" listener to add your new virtual host to its "Virtual Host Mappings", or create a new listener for it.

Enabling HTTPS (SSL/TLS)

Step 10: Obtain a Free Certificate with Let's Encrypt

It's recommended to use the built-in ACME client (`olsacme.sh`) to automatically obtain and renew certificates.

sudo /usr/local/lsws/admin/misc/acme.sh -i

Follow the interactive prompts to enter your domain name and email address. The script will configure everything automatically.

Once complete, you need to change the listener port to 443, enable SSL, and select the generated certificate file in the listener settings.

Common Management Commands

• Start service: sudo systemctl start lshttpd
• Stop service: sudo systemctl stop lshttpd
• Restart service: sudo systemctl restart lshttpd
• Check service status: sudo systemctl status lshttpd
• View error log: tail -f /usr/local/lsws/logs/error.log
• View access log: tail -f /usr/local/lsws/logs/access.log

Troubleshooting and Notes

• Port Conflict: If Apache or Nginx is already running, stop them first (sudo systemctl stop apache2 nginx) or modify OpenLiteSpeed's listener port.
• Firewall: Ensure the firewall (e.g., UFW) allows the relevant ports (80, 443, 7080). sudo ufw allow 80,443,7080/tcp
• File Permissions: Ensure the website directory has read and execute permissions for the OpenLiteSpeed runtime user (typically `nobody`).
• PHP Not Executing: Check that the virtual host's script handler configuration is correctly associated and that the PHP LSAPI application was created properly.

After completing these steps, your OpenLiteSpeed server should be configured and ready to run PHP websites. For a production environment, further optimization and stricter security policies are recommended.