Overview

There are two ways to install the store by hand:

• With Docker - recommended. PostgreSQL and Redis come pre-configured, and the deployment is OS-agnostic.
• Directly on the host - PHP, PostgreSQL and a webserver installed and wired up yourself.

Both leave the webserver to you - each path has its own section for linking a domain and adding HTTPS.

Installing with Docker

This is the recommended way to install the store by hand, as it provides:

• OS-agnostic deployment
• Pre-configured components (PostgreSQL, Redis, etc.)
• Isolated environment
• Easy updates and maintenance

Installing Docker

You'll need Docker and docker-compose installed on your system. Choose your platform below:

• Linux (most servers): Follow the Docker Engine Installation Guide for your specific distribution or run this convincience script to get started quickly:

curl -fsSL https://get.docker.com | sudo sh

• Windows: Install Docker Desktop for Windows

• Mac: Install Docker Desktop for Mac

Installing Light Store

Now that Docker is set up, you can proceed with installing Light Store.

1. Download the Light Store package from BuiltByBit.

2. Extract the package:

   unzip "Light Store v21.1.0.zip"

3. Start the containers:

   docker compose up -d --build

4. Configure the reverse proxy:

   • For HTTP: Use http://your-server-ip:8001 (default port).
   • For HTTPS: Follow Linking a domain below to serve the store on your domain over HTTPS.
   The default port (8001) can be modified in docker-compose.yml if needed.

5. Enter the page and follow the installation steps.

Linking a domain

The store answers on port 8001 over plain HTTP. To serve it on your domain, put a reverse proxy in front of it. Every option below forwards requests to port 8001; they differ in how HTTPS is handled:

• Caddy - obtains and renews the certificates itself, no extra tooling.
• Nginx with SSL - certificates issued and renewed by Certbot.
• Nginx without SSL - plain HTTP, for when something upstream already terminates SSL.

Before configuring the webserver, point your domain's DNS at the server:

1. Log in to your domain registrar's control panel (e.g., Cloudflare, GoDaddy, Namecheap)
2. Add an A record:
   • Type: A
   • Name: @ (for root domain) or store (for store.yourdomain.com)
   • Value: Your server's IP address
   • TTL: Auto or 3600 (1 hour)

Managing your installation

Here are some useful commands for managing your Light Store installation:

# (Re)start store
docker compose up -d --build
# The --build flag may be ommited if no code changes have been made.
# However, it is recommended to re-build each time, in case changes were made.

# Stop store
docker compose down

# View logs
docker compose logs -f app

Installing directly on the host

Light Store is built on top of the Laravel framework - therefore, deployment steps for Laravel apply. This guide outlines the steps to deploy Light Store on a fresh installation of a Ubuntu 24.04 full-root server.

Prerequisites

Before you begin, this guide will assume a fresh installation of a Ubuntu 24.04 full-root server.

Dependencies Installation

apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg

LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php

# Add PostgreSQL repository
sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

apt update

# Add universe repository if you are on Ubuntu 18.04
apt-add-repository universe

apt -y install php8.5 php8.5-{common,cli,gd,pgsql,mbstring,bcmath,xml,fpm,curl,zip} postgresql postgresql-contrib nginx tar unzip git

Composer Installation

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Code Upload

Upload the store files to your server. You can do it via FTP or SSH.

# Make a directory for the store files:
mkdir /var/www/lightstore
cd /var/www/lightstore
# Extract the files if uploaded as .tar.gz:
tar -xzvf lightstore.tar.gz
# ...or unzip the files if uploaded as .zip:
unzip "Light Store v21.1.0.zip"
# Make sure to adjust permissions:
chmod -R 755 storage/* bootstrap/cache/

Database Setup

It is possible to use the panel with a local SQLite database. However, it is advised to use PostgreSQL for production instead.

# Switch to postgres user to create the database
sudo -u postgres psql

# Create a new user and database
CREATE USER lightstore WITH PASSWORD 'yourPassword';
CREATE DATABASE lightstore;
GRANT ALL PRIVILEGES ON DATABASE lightstore TO lightstore;
\q

Copy over the default environment settings file, install composer dependencies, and then generate a new application encryption key.

cp .env.example .env
composer install --no-dev --optimize-autoloader

# Only run the command below if you are installing this app for
# the first time and do not have any data in the database.
# This will override the existing APP_KEY in the .env file.
php artisan key:generate --force
# Link the storage:
php artisan storage:link

Environment Setup

Copy over .env.example to .env and change the database connection information to match the credentials you created in the previous step.

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=lightstore
DB_USERNAME=lightstore
DB_PASSWORD=yourPassword

Web Server Configuration

Be sure to replace yourdomain.com with your domain name.

Permissions Setup

Fix the permissions of lightstore with the following command:

chown -R www-data:www-data /var/www/lightstore/*

Scheduled Tasks

You'll need to create a new cronjob that runs every minute to process specific Light Store tasks. Open crontab using sudo crontab -e and then paste the line below.

* * * * * php /var/www/lightstore/artisan schedule:run >> /dev/null 2>&1

Queue Worker Setup

Create a new file in /etc/systemd/system/ called lightstore.service and add the following:

[Unit]
Description=Light Store Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/lightstore/artisan queue:work
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

Then run the following commands to enable the service and start it:

sudo systemctl enable --now lightstore.service

Asset Building

In case of needing to rebuild assets, you can do so using Node.js.

If you do not have Node.js installed, install it using either apt or nvm (node version manager, recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

Restart your shell.

Then install the version 24 of Node.js:

nvm install 24

Once Node.js is installed, enable pnpm 11 through Corepack (bundled with Node.js):

corepack enable
corepack prepare pnpm@11 --activate

Then install the dependencies for the project:

cd /var/www/lightstore
pnpm install

Finally, you can build the assets:

pnpm run build