Lightspeed Documentation

Lightspeed is a lightweight, rapid development tool for building and deploying PHP websites. Get from zero to production in minutes with our streamlined CLI workflow.

Installation

Install the Lightspeed CLI to get started. Choose the installation method for your platform.

macOS / Linux

Install with a single command using curl:

curl -sfL https://raw.githubusercontent.com/abrayall/lightspeed/refs/heads/main/install.sh | sh -

Windows (PowerShell)

On Windows, use PowerShell to install:

irm https://raw.githubusercontent.com/abrayall/lightspeed/refs/heads/main/install.ps1 | iex

From Source

Alternatively, you can build from source:

git clone https://github.com/abrayall/lightspeed.git
cd lightspeed
./install.sh

Verify Installation

After installation, verify that Lightspeed is installed correctly:

lightspeed --version

Quick Start

Get your first Lightspeed site up and running in under 5 minutes.

1. Create a New Project

Create a directory for your project and initialize it:

mkdir my-awesome-site && cd my-awesome-site
lightspeed init

This creates the basic project structure with a starter index.php, CSS files, and configuration.

2. Start the Development Server

Launch the local development server:

lightspeed start

Your site is now running at http://localhost:9000. Changes to your files are reflected immediately.

3. Build Your Site

Edit your PHP, HTML, CSS, and JavaScript files. The development server supports:

• Clean URLs - Access /about instead of /about.php
• Hot reload - Changes appear instantly in the browser
• PHP includes - Organize your code with includes

4. Deploy to Production

When you're ready to go live, deploy with a single command:

lightspeed deploy

Your site will be live at https://my-awesome-site.lightspeed.ee

Requirements

Before using Lightspeed, ensure you have the following installed:

Supported Platforms

• macOS (Intel and Apple Silicon)
• Linux (x64 and ARM64)
• Windows 10/11 (with WSL2 recommended)

CLI Commands

lightspeed init

Initialize a new Lightspeed project with the basic directory structure and starter files.

lightspeed init
lightspeed init --name mysite
lightspeed init --name mysite --domain example.com
lightspeed init -d example.com -d www.example.com

Options

Files Created

• site.properties - Site configuration
• index.php - Hello World starter page
• assets/css/style.css - Basic stylesheet
• assets/js/ - JavaScript directory
• includes/ - PHP includes directory
• .idea/ - PhpStorm project configuration
• .gitignore - Git ignore file

lightspeed start

Start a PHP development server using Docker. The server mounts your current directory and serves it with hot reload capabilities.

lightspeed start
lightspeed start --port 8080
lightspeed start --image custom-server

Options

Features

• Clean URLs - Access /about instead of /about.php
• Automatic PHP library loading - Libraries from ~/.lightspeed/library/
• Hot reload - Changes are reflected immediately

lightspeed stop

Stop the running development server.

lightspeed stop

lightspeed build

Build a Docker container for production deployment. The image is optimized for the linux/amd64 platform.

lightspeed build
lightspeed build --tag 1.0.0
lightspeed build --image custom-base-image

Options

lightspeed publish

Build and push the Docker image to the Lightspeed registry. This pushes both the versioned tag and a latest tag.

lightspeed publish
lightspeed publish --tag 1.0.0
lightspeed publish --name my-site

Options

lightspeed deploy

Build, push, and deploy your site to production. If the app doesn't exist, it will be created automatically.

lightspeed deploy
lightspeed deploy --name my-production-site

Options

After deployment, your site will be accessible at:

• https://[name].lightspeed.ee - Automatically configured subdomain

Configuration

site.properties

The site.properties file in your project root configures your site. Here's a complete example:

# Site name (used for [name].lightspeed.ee)
name=mysite

# Custom domains
domain=example.com
domains=www.example.com,app.example.com

# Base image (pin to specific version)
image=0.5.4

# PHP libraries (for include path)
libraries=lightspeed

Configuration Options

Image Property Examples

# Use specific version
image=0.5.4

# Use latest
image=latest

# Use custom image
image=ghcr.io/myorg/myimage:latest

Libraries Property Examples

# Use lightspeed library (matches CLI version)
libraries=lightspeed

# Use specific lightspeed version
libraries=lightspeed:v0.5.0

# Multiple libraries
libraries=lightspeed,/path/to/custom/lib

Custom Domains

You can configure custom domains for your site in site.properties:

# Single domain
domain=example.com

# Multiple domains
domains=www.example.com,app.example.com,api.example.com

DNS Configuration

Point your custom domain to Lightspeed by creating a CNAME record:

Environment Variables

You can pass environment variables to your application for configuration:

<?php
// Access environment variables
$apiKey = getenv('API_KEY');
$debugMode = getenv('DEBUG') === 'true';
?>

Common environment variables available in your Lightspeed application:

Project Structure

Directory Layout

A typical Lightspeed project has the following structure:

mysite/
├── site.properties     # Site configuration
├── index.php           # Main entry point
├── about.php           # Additional pages
├── contact.php
├── assets/
│   ├── css/
│   │   └── style.css   # Stylesheets
│   ├── js/
│   │   └── main.js     # JavaScript files
│   └── images/         # Image assets
├── includes/           # PHP includes
│   ├── header.php
│   ├── footer.php
│   └── functions.php
├── .idea/              # PhpStorm configuration
│   └── php.xml         # PHP include paths
├── .gitignore          # Git ignore file
└── Dockerfile          # Generated on build

Assets & Static Files

Static assets like CSS, JavaScript, and images are served from the assets/ directory:

<!-- CSS -->
<link rel="stylesheet" href="/assets/css/style.css">

<!-- JavaScript -->
<script src="/assets/js/main.js"></script>

<!-- Images -->
<img src="/assets/images/logo.png" alt="Logo">

Recommended Organization

• assets/css/ - Stylesheets
• assets/js/ - JavaScript files
• assets/images/ - Images and icons
• assets/fonts/ - Custom fonts

PHP Includes

The includes/ directory is for PHP files that are included by other files. This is perfect for headers, footers, and shared functions.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title><?php echo $pageTitle ?? 'My Site'; ?></title>
    <link rel="stylesheet" href="/assets/css/style.css">
</head>
<body>
    <header>
        <nav>...</nav>
    </header>

<?php
$pageTitle = 'Home';
include 'includes/header.php';
?>

<main>
    <h1>Welcome to my site</h1>
</main>

<?php include 'includes/footer.php'; ?>

Routing & Clean URLs

Lightspeed automatically provides clean URLs without the .php extension:

PHP Library

Using the Library

Lightspeed includes a PHP library that's automatically available in the server image at /opt/lightspeed/. The PHP include path is configured automatically.

<?php
require_once('lightspeed/version.php');

echo lightspeed_version(); // Returns the Lightspeed version
?>

The library is downloaded to ~/.lightspeed/library/v[version]/ on first use.

Available Functions

The Lightspeed PHP library provides several utility functions:

IDE Support

When you run lightspeed init or any lightspeed command in a project with .idea/ and site.properties, the PhpStorm include paths are automatically updated to point to the resolved library locations.

This enables:

• Code completion for Lightspeed library functions
• Go-to-definition for library code
• Error checking for undefined functions

Deployment

Deployment Workflow

The typical deployment workflow consists of three steps:

Or, use the all-in-one command that performs all three steps:

lightspeed deploy

Docker Images

Lightspeed builds production Docker images optimized for PHP hosting. The build process:

1. Creates a Dockerfile in your project root
2. Copies your site files to /var/www/html/
3. Sets appropriate permissions
4. Tags the image with your site name and version

FROM ghcr.io/abrayall/lightspeed-server:0.6.3
COPY . /var/www/html/
RUN chown -R www-data:www-data /var/www/html

Server Image

Lightspeed uses a custom server image (ghcr.io/abrayall/lightspeed-server) based on:

• PHP 8.2 FPM - Latest PHP with performance optimizations
• Nginx - High-performance web server

Features

• Clean URLs (no .php extension required)
• Pre-configured PHP include path for Lightspeed library
• Optimized for small PHP sites
• Gzip compression enabled
• Security headers configured

SSL & CDN

All Lightspeed deployments include:

Advanced

Versioning

Lightspeed uses git tags for versioning. When you build or publish, the version is automatically determined from your git history:

# Tag a release
git tag v1.0.0
git push --tags

# Build with the version
lightspeed build
# Image: registry.lightspeed.ee/mysite:1.0.0

If no git tag is found, the version defaults to latest.

Custom Libraries

You can add custom PHP libraries to your project by specifying them in site.properties:

# Multiple libraries
libraries=lightspeed,/path/to/custom/lib,/another/library

Libraries are added to the PHP include path, so you can use require_once() with relative paths:

<?php
require_once('mylib/helper.php');
require_once('anotherlib/utils.php');
?>

Troubleshooting

Docker not running

If you see an error about Docker, make sure Docker Desktop is running:

# Check if Docker is running
docker info

# Start Docker Desktop (macOS)
open -a Docker

Port already in use

If port 9000 is already in use, specify a different port:

lightspeed start --port 8080

Permission denied

If you see permission errors during install, you may need to use sudo:

sudo ./install.sh

Getting Help

If you encounter issues not covered here:

• Check the GitHub Issues for known problems
• Run lightspeed --help for command usage
• Contact support for deployment issues