DOCSEARCHbyAlgolia
Submit Docs

OpenLiteSpeed WordPress Docker Environment

repository·master·Indexed 42 days ago

https://github.com/litespeedtech/ols-docker-env

A lightweight, pre-configured Docker stack for WordPress on Ubuntu 26.04, including OpenLiteSpeed, MariaDB, PHP, Redis, and phpMyAdmin. Features built-in CLI scripts for managing virtual hosts, automated WordPress installation via appinstall.sh, and SSL certificate management using ACME (Let's Encrypt) and mkcert.

Tokens
8.6K
Snippets
43
Records
50
Agent score
52%

What's inside OpenLiteSpeed WordPress Docker Env

  1. Understand the Project Data Structure

    master

    The following directory structure is maintained in the cloned project:

    • acme/: Applied Let's Encrypt certificates.
    • bin/: CLI scripts for managing virtual hosts, applications, upgrades, etc.
    • data/db/: MySQL database storage.
    • logs/: Web server and virtual host logs (access.log, error.log, lsrestart.log, stderr.log).
    • lsws/: OpenLiteSpeed configuration files (admin-conf, conf).
    • sites/: Document roots (where WordPress files are installed).
    • acme/: Contains all applied certificates from Lets Encrypt.

  2. Customize the Docker Image

    master

    To add custom packages (e.g., lsphp83-pspell), extend the image using a custom Dockerfile.

    1. Create a custom/Dockerfile:
      FROM litespeedtech/openlitespeed:latest
RUN apt-get update && apt-get install lsphp83-pspell -y
    2. Update docker-compose.yml to use the build context:
      litespeed:
  image: litespeedtech/openlitespeed:${OLS_VERSION}-${PHP_VERSION}
  build: ./custom
    3. Rebuild and start: docker compose up --build
    FROM litespeedtech/openlitespeed:latest
RUN apt-get update && apt-get install lsphp83-pspell -y

  3. Manage Databases and WordPress Installation

    master

    The environment provides scripts to automate database creation and WordPress setup.

    Create a Database

    Auto-generate credentials: bash bin/database.sh [-D, --domain] example.com

    Specify custom credentials: bash bin/database.sh [-D, --domain] example.com [-U, --user] USER_NAME [-P, --password] MY_PASS [-DB, --database] DATABASE_NAME

    Install WordPress

    To preconfigure the wp-config file, you must run the database.sh script for your domain before running the installation script: bash bin/appinstall.sh [-A, --app] wordpress [-D, --domain] example.com

    # 1. Create DB
bash bin/database.sh --domain example.com --user myuser --password mypass --database mydb

# 2. Install WP
bash bin/appinstall.sh --app wordpress --domain example.com

  4. Install and Setup OpenLiteSpeed WordPress Docker Container

    master

    To set up a lightweight WordPress environment with OpenLiteSpeed on Ubuntu 26.04, follow these steps:

    1. Prerequisites: Ensure Docker and Docker Compose are installed.
    2. Clone the repository:
      git clone https://github.com/litespeedtech/ols-docker-env.git
cd ols-docker-env
    3. Configure: Edit the .env file to set your demo site domain, default MySQL user, and password.
    4. Launch: Run the containers using Docker Compose.

    If you need to run a single web server container instead of the full stack, refer to the ols-dockerfiles usage guide.

    git clone https://github.com/litespeedtech/ols-docker-env.git
cd ols-docker-env
docker compose up

  5. Use mkcert for Local Development SSL

    master

    For local domains (e.g., .test, .local), use mkcert to generate trusted certificates without browser warnings.

    1. Install mkcert (Windows with Chocolatey): bash bin/mkcert.sh --install
    2. Generate Certificate (Domain must be added via domain.sh first): bash bin/mkcert.sh [-D, --domain] example.test
    3. Remove Certificate (Reverts to HTTP): bash bin/mkcert.sh [-R, --remove] [-D, --domain] example.test
    # Install CA
bash bin/mkcert.sh --install

# Generate SSL for local domain
bash bin/mkcert.sh --domain example.test

  6. Manage Docker Containers

    master

    Use standard Docker Compose commands to manage the lifecycle of your OpenLiteSpeed environment:

    • Start containers: docker compose up (or docker compose up -d for daemon/background mode).
    • Stop containers: docker compose stop.
    • Remove containers: docker compose down (stops and removes all containers).
    docker compose up -d
docker compose stop
docker compose down

  7. Manage MySQL databases with database.sh

    master

    The database.sh script is a CLI utility used to create, configure, or delete MySQL databases within the OpenLiteSpeed Docker environment. It can either auto-generate credentials based on a domain name or allow you to specify custom database names, users, and passwords.

    Key Capabilities

    • Auto-generation: Provide a domain name, and the script generates a sanitized database name, username, and a secure random password.
    • Manual Configuration: Explicitly define the database name, user, and password.
    • Credential Storage: When a database is created, credentials are automatically stored in ./sites/[DOMAIN]/.db_pass.
    • Cleanup: Delete existing databases and users.

    Validation Rules

    • Identifiers (User/DB): Must be alphanumeric or underscores ([A-Za-z0-9_]), maximum 63 characters.
    • Passwords: Minimum 8 characters. Forbidden characters include ', ", \, $, and `.
    • Domains: Must be a valid domain format or localhost.
    # Example: Auto-generate database for a domain
./database.sh --domain example.com

# Example: Create a specific database with custom credentials
./database.sh --domain example.com --database my_db --user my_user --password my_secure_password

# Example: Delete a database
./database.sh --delete --database my_db --user my_user

  8. How appinstallctl.sh handles database credentials

    master

    The appinstallctl.sh script does not take database credentials as arguments. Instead, it expects a .db_pass file to exist in the Virtual Host directory. This file is used to pre-configure the WordPress wp-config.php file.

    Expected File Location

    • /var/www/vhosts/[DOMAIN_OR_VHNAME]/.db_pass

    Expected File Format The script parses the file for specific keys using awk. The file should contain lines similar to:

    Database: "your_db_name"
Username: "your_db_user"
Password: "your_db_password"

  9. Install mkcert via mkcert.sh

    master

    The --install flag automates the installation of the mkcert utility and its local Certificate Authority (CA) based on your operating system:

    • Windows: Uses choco install mkcert -y (requires Chocolatey).
    • macOS: Uses brew install mkcert nss (requires Homebrew).
    • Linux: Uses apt, dnf, yum, or zypper to install mkcert and NSS tools.

    After installation, it runs mkcert -install to configure the local CA.

    bash bin/mkcert.sh --install

  10. Revoke or Remove a domain from ACME

    master

    If you no longer need a certificate, you can either revoke it or remove it entirely.

    • Revoke a domain: Use -v or --revoke to revoke the certificate via Let's Encrypt.
    • Remove a domain: Use -V or --remove to remove the domain from the local ACME management.

    Both operations trigger a LiteSpeed restart.

    acme.sh --domain example.com --revoke
acme.sh --domain example.com --remove
    acme.sh --domain example.com --revoke

  11. Use mkcert.sh to manage local SSL certificates

    master

    The mkcert.sh script is a CLI tool used to generate and manage local development SSL certificates for OpenLiteSpeed running in Docker. It automates the process of creating certificates via mkcert, copying them into the container, and reconfiguring OpenLiteSpeed templates to enable HTTPS for specific domains.

    Prerequisites

    • A running OpenLiteSpeed Docker container (default name: litespeed).
    • The domain must already be added to the environment (e.g., via bash bin/domain.sh -a <domain>) before generating certificates.

    Common Workflows

    1. Install mkcert

    If you do not have mkcert installed on your host machine, use the --install flag. This will attempt to install it using your system's package manager (Chocolatey for Windows, Homebrew for macOS, or apt/dnf/yum/zypper for Linux) and configure the local CA.

    2. Generate and Configure SSL for a Domain

    To create a certificate for a domain (and its www variant) and automatically configure OpenLiteSpeed to use it:

    bash bin/mkcert.sh --domain example.test

    3. Remove SSL Configuration for a Domain

    To revert a domain to standard HTTP and remove the generated certificate files from both the host and the container:

    bash bin/mkcert.sh --remove --domain example.test
    # Install mkcert
bash bin/mkcert.sh --install

# Generate SSL for a domain
bash bin/mkcert.sh --domain example.test

# Remove SSL for a domain
bash bin/mkcert.sh --remove --domain example.test

  12. Create a database with auto-generated credentials

    master

    To quickly set up a database for a specific site, use the --domain flag. The script will:

    1. Validate the domain.
    2. Generate a random 12-character base64 password.
    3. Sanitize the domain name to create a valid SQL identifier (removing . and &).
    4. Create the database and user in MySQL.
    5. Save the credentials to ./sites/[DOMAIN]/.db_pass in JSON-like format.

    Note: The database and username will be identical, derived from the domain name.

    ./database.sh --domain example.com