OpenLiteSpeed Docker Reverse Proxy

This project runs the official litespeedtech/openlitespeed image as a Dockerized OpenLiteSpeed reverse proxy. The primary .env domain uses the default Example virtual host, and optional additional domains use standalone virtual hosts instead of virtual-host templates.

The configuration includes:

• A per-VH OLS proxy External App (proxy_backend, proxy_backend2, and so on).
• A RewriteRule that proxies all requests to the backend.
• HTTP and HTTPS listeners on ports 80 and 443, including UDP 443 for HTTP/3 QUIC.
• OpenLiteSpeed native ACME certificate management.

Configuration

Copy the example environment file and edit the values:

cp .env.example .env

OLS_IMAGE=litespeedtech/openlitespeed:latest
BACKEND_IP=192.168.0.1
BACKEND_PORT=1234
DOMAIN=www.example.com
ACME_EMAIL=

DOMAIN is used for the OLS listener mapping and is sent to the backend as the Host header.

BACKEND_IP is the backend host, not necessarily a numeric IP address. It may be an IP address, DNS hostname, or Docker service/container name such as backend-service when both containers share a Docker network. Use the backend container port in that case; for example, backend-service:8080, not the host-published port from a host-port:container-port mapping.

Set PROXY_SOCKET=true to add an OpenLiteSpeed WebSocket proxy block. By default, it reuses BACKEND_IP and BACKEND_PORT, which is the usual setup when HTTP and WebSocket traffic belong to the same application. Set PROXY_SOCKET_IP and PROXY_SOCKET_PORT only when the WebSocket service uses a different backend.

Additional domains

The .env configuration always defines the primary single-domain proxy and remains backward compatible. If additional domains are required, add one valid entry per line to domains.conf:

DOMAIN, BACKEND_IP, BACKEND_PORT, PROXY_SOCKET
second.example.com, backend-service, 8080, false

The primary .env domain remains the Example virtual host. Each line in domains.conf creates an additional virtual host named from the domain, an independent proxy External App, an HTTP/HTTPS listener mapping, and its own ACME-enabled VHost configuration. The primary VHost uses proxy_backend; additional VHosts use proxy_backend2, proxy_backend3, and so on. Do not add OLS_IMAGE or ACME_EMAIL to domains.conf; those settings remain global in .env.

PROXY_SOCKET must be exactly true or false. When it is true, the WebSocket backend uses the same host and port from that line. The parser rejects missing fields, invalid domains, invalid backend hosts, invalid ports, invalid Boolean values, duplicate domains, and extra comma-separated fields.

The file is mounted read-only into the container, so changing domains.conf does not require an image rebuild. Restart the proxy after changes:

docker compose up -d

Connect another Docker stack

Compose creates a shared bridge network named ls-net. Any backend container that should be reached by its Docker service or container name must join this network.

For a backend in another Compose project, add the external network to that project's docker-compose.yml:

services:
  backend:
    networks:
      - ls-net

networks:
  ls-net:
    external: true
    name: ls-net

Then use the backend service name and its internal container port in .env:

BACKEND_IP=backend
BACKEND_PORT=8080

For a container started with docker run, attach it to the shared network:

docker network connect ls-net <backend-container-name>

Use the container's internal listening port, not a host port mapping. For example, a 3000:8080 mapping is reached from OLS as backend:8080 when both containers use ls-net.

Start command

Start the proxy:

docker compose up -d

The first startup builds the local image automatically. It may also pull the selected OpenLiteSpeed base image.

View status and logs:

docker compose ps
docker compose logs -f ols-proxy

Changing .env requires restarting the container:

docker compose down
docker compose up -d

Changing domains.conf only requires restarting the container. Changing Dockerfile or docker-entrypoint.sh requires rebuilding:

docker compose up -d --build

FAQ

How to visit WebAdmin

WebAdmin port 7080 is disabled by default. If needed, uncomment - "7080:7080" under ports, then recreate the container:

docker compose up -d

Set or reset the WebAdmin password interactively:

docker compose exec ols-proxy /usr/local/lsws/admin/misc/admpass.sh