> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sitestorepro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and Configure Site Store Pro

> Set up Site Store Pro with PHP 8.3+, configure your database and environment, run migrations, seed default data, compile assets, and add optional payment SDKs.

This guide walks you through a complete Site Store Pro installation — from meeting server requirements and configuring your environment to running database migrations, seeding demo data, compiling frontend assets, and enabling optional payment provider SDKs. Follow the steps in order for the smoothest setup experience.

## Requirements

Before you begin, make sure your local environment meets the following requirements:

<CardGroup cols={2}>
  <Card title="PHP 8.3+" icon="php">
    Site Store Pro requires PHP 8.3 or higher with the standard Laravel extensions enabled (BCMath, Ctype, Fileinfo, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML). (PHP 8.5 Recommended)
  </Card>

  <Card title="Composer" icon="box">
    Composer is required to install PHP dependencies. Ensure you have the latest stable version installed globally.
  </Card>

  <Card title="Node.js & npm" icon="node">
    Node.js (LTS recommended) and npm are required to install and compile frontend assets.
  </Card>

  <Card title="Database" icon="database">
    MySQL / MariaDB / Amazon RDS. MySQL 8+ or MariaDB 10.6+ is preferred.
  </Card>
</CardGroup>

<Note>
  The `phpoffice/phpspreadsheet` package is required if you plan to use the bulk CSV/spreadsheet product import feature. It is not bundled by default — see [step 9](#optional-install-bulk-excel-file-import-support) below.
</Note>

***

## Installation Steps

<Steps>
  <Step title="Clone the Repository">
    Clone the Site Store Pro repository to your local machine (or online server / AWS EC2/ECS instance) and navigate into the project directory:

    ```bash theme={null}
    git clone https://github.com/Site-Store-Pro/laravel-ecommerce [your-install-name]
    cd [your-install-name]
    ```
  </Step>

  <Step title="Install PHP and Node Dependencies">
    Install all backend and frontend dependencies:

    <CodeGroup>
      ```bash PHP Dependencies theme={null}
      composer install
      ```

      ```bash Node Dependencies theme={null}
      npm install
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure Your Environment">
    Copy the example environment file and generate your application key:

    ```bash theme={null}
    cp .env.example .env
    php artisan key:generate
    ```

    Open the newly created `.env` file and update the database configuration to match your db setup and install URL (both APP\_URL and ASSET\_URL should reflect be the same URL value) and your install's subdirectory (if applicable);

    ```env theme={null}
    APP_NAME="Your Online Store Name"
    APP_URL=http://localhost
    ASSET_URL=http://localhost

    LIVEWIRE_SUBDIRECTORY=
    # example /sub-dir-name


      DB_CONNECTION=mysql
      DB_HOST=127.0.0.1
      DB_PORT=3306
      DB_DATABASE=your_database_name
      DB_USERNAME=your_db_user
      DB_PASSWORD=your_db_password
    ```
  </Step>

  <Step title="Create Storage Directories & Set Permissions (AWS EC2 / ECS / Linux)">
    When installing on an **AWS EC2 / ECS instance (Amazon Linux)** or remote server, ensure that all framework storage directories exist and have proper ownership and write permissions for `ec2-user:apache` (or `www-data` on Ubuntu):

    <CodeGroup>
      ```bash AWS EC2 / ECS (Amazon Linux) theme={null}
      # 1. Create missing framework storage folders
      mkdir -p storage/framework/{cache/data,sessions,views,testing} storage/logs bootstrap/cache

      # 2. Set ownership to ec2-user:apache
      sudo chown -R ec2-user:apache storage bootstrap/cache

      # 3. Grant write permissions and set group inheritance (SetGID 2775)
      sudo chmod -R 2775 storage bootstrap/cache
      ```

      ```bash Ubuntu / Debian (Nginx or Apache) theme={null}
      # 1. Create missing framework storage folders
      mkdir -p storage/framework/{cache/data,sessions,views,testing} storage/logs bootstrap/cache

      # 2. Set ownership to www-data
      sudo chown -R www-data:www-data storage bootstrap/cache
      sudo chmod -R 775 storage bootstrap/cache
      ```
    </CodeGroup>

    <Warning>
      If `storage/framework/views` or other storage folders are missing or unwritable by Apache/PHP, PHP will trigger an error: `tempnam(): file created in the system's temporary directory`.
    </Warning>
  </Step>

  <Step title="Run Database Migrations and Seed">
    Run a fresh migration and seed the database with all default data:

    ```bash theme={null}
    php artisan migrate:fresh --seed
    ```

    The seeder creates all default roles, a home page, common cms pages such as privacy, about us, contact us, an admin account, and sample configuration. A fresh install typically completes in under a minute.

    <Warning>
      `migrate:fresh` will **drop all existing tables** and rebuild from scratch. Never run this command on a production database or any database containing data you need to keep.
    </Warning>
  </Step>

  <Step title="(Optional) Load Developer QA Seed Data">
    If you want to install a demo storefront with sample (training) data:

    ```bash theme={null}
    php artisan db:seed --class=DemoStoreSeeder
    ```
  </Step>

  <Step title="Compile Frontend Assets">
    Build the frontend assets using Vite:

    <Tabs>
      <Tab title="Development">
        Starts a Vite dev server with hot module replacement (HMR):

        ```bash theme={null}
        npm run dev
        ```
      </Tab>

      <Tab title="Production">
        Compiles and minifies assets for production deployment:

        ```bash theme={null}
        npm run build
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="(Optional) Install Payment SDK Dependencies">
    Site Store Pro supports Stripe, Paddle (and Paypal) as BUILT-IN (default) payment providers.

    <CodeGroup>
      ```bash Stripe Only theme={null}
      composer require stripe/stripe-php
      ```

      ```bash Paddle Only theme={null}
      composer require paddlehq/paddle-php-sdk
      ```

      ```bash Both Stripe and Paddle theme={null}
      composer require stripe/stripe-php paddlehq/paddle-php-sdk
      ```
    </CodeGroup>

    <Note>
      Payment provider credentials (API keys, webhook secrets, etc.) are configured via your `.env` file after the respective SDK is installed. Refer to the Payment Configuration guide for full setup instructions.
    </Note>
  </Step>

  <Step title="(Optional) Install Bulk Excel File Import Support">
    To enable bulk product import and export via Excel spreadsheet files, install the `phpoffice/phpspreadsheet` package:

    ```bash theme={null}
    composer require phpoffice/phpspreadsheet
    ```
  </Step>

  <Step title="Create the Storage Symlink">
    In production (and recommended for local development too), create the public storage symlink so uploaded files are accessible via the browser:

    ```bash theme={null}
    php artisan storage:link
    ```

    <Warning>
      Without this symlink, product images and other uploaded media will **not** be publicly accessible. This step is required for any environment where file uploads are used.
    </Warning>
  </Step>
</Steps>

***

## Default Admin Login

After running migrations and seeding, your Site Store Pro installation includes a default administrator account:

<Card title="Default Admin Credentials" icon="lock">
  | Field        | Value                 |
  | ------------ | --------------------- |
  | **URL**      | `/admin`              |
  | **Email**    | `admin@support.local` |
  | **Password** | `SampleUser12345#`    |
</Card>

<Warning>
  Change the default admin password immediately after your first login, especially before deploying to any publicly accessible environment. To Change The Temporary (Default) Password: Click on Top Right Green Dot (Next To Light/Dark Mode Icon) Then Click On 'My Profile' (Update Password Section Is On Middle Of Page)
</Warning>

***

## Quick Reference

<Accordion title="Full Installation Command Sequence (AWS EC2 / ECS / Linux)">
  ```bash theme={null}
  # 1. Clone and enter the project
  git clone https://github.com/Site-Store-Pro/laravel-ecommerce [your-install-name]
  cd [your-install-name]

  # 2. Install dependencies
  composer install
  npm install

  # 3. Environment setup
  cp .env.example .env
  php artisan key:generate

  # 4. Create missing storage directories & set ec2-user:apache permissions
  mkdir -p storage/framework/{cache/data,sessions,views,testing} storage/logs bootstrap/cache
  sudo chown -R ec2-user:apache storage bootstrap/cache
  sudo chmod -R 2775 storage bootstrap/cache

  # 5. Run migrations and seed
  php artisan migrate:fresh --seed

  # 6. Compile assets
  npm run build

  # 7. Create storage symlink
  php artisan storage:link
  ```
</Accordion>

<Accordion title="Optional Extras">
  ```bash theme={null}
  # Demo Store Seeding
  php artisan db:seed --class=DemoStoreSeeder

  # Stripe payment SDK
  composer require stripe/stripe-php

  # Paddle payment SDK
  composer require paddlehq/paddle-php-sdk

  # Bulk import support
  composer require phpoffice/phpspreadsheet

  # Redis support (pure PHP driver)
  composer require predis/predis
  ```
</Accordion>

***

# Local Docker Development Setup Guide

This guide details how to set up and run the Site Store Pro Laravel eCommerce application locally in an isolated multi-container environment using Docker.

***

## Step 1: Install System Prerequisites

### For Windows Users

Docker requires Windows Subsystem for Linux (WSL 2) to run efficiently.

1. Open PowerShell as an Administrator and execute:
   ```bash theme={null}
   wsl --install
   ```
2. Restart your computer when the process completes.
3. Download and install Docker Desktop for Windows.
4. During installation, verify that the "Use WSL 2 instead of Hyper-V" setting is enabled.

### For macOS Users

Docker runs natively via the macOS Hypervisor framework.

1. Download the correct version of Docker Desktop for Mac:
   * Mac with Apple Silicon (M1, M2, M3, M4 chips)
   * Mac with Intel chip
2. Double-click the downloaded `.dmg` file, drag the Docker icon into your Applications folder, and launch it.
3. Grant the required privileged permissions when prompted by macOS.

***

## Step 2: Prepare Your Local Repository

1. Open your terminal (PowerShell on Windows, or Terminal on macOS) and clone the application:
   ```bash theme={null}
   git clone https://github.com/Site-Store-Pro/laravel-ecommerce [your-install-name]
   cd [your-install-name]
   ```

2. Initialize your local configuration file from the template:
   * Windows (PowerShell): `Copy-Item .env.example .env`
   * macOS (Terminal): `cp .env.example .env`

3. Create the Nginx reverse-proxy configuration folder structure:
   * Windows (PowerShell): `New-Item -Path "docker/nginx" -ItemType "directory" -Force`
   * macOS (Terminal): `mkdir -p docker/nginx`

***

## Step 3: Add the Configuration Files

Create the following three files in your project root folder:

### 1. `Dockerfile`

```dockerfile theme={null}
# === STAGE 1: Frontend Asset Builder ===
FROM node:20-alpine AS frontend-builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# === STAGE 2: PHP Dependency Application ===
FROM php:8.3-fpm-alpine AS backend-builder
WORKDIR /var/www
RUN apk add --no-cache git unzip libzip-dev libpng-dev libjpeg-turbo-dev freetype-dev icu-dev curl-dev
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install zip pdo_mysql bcmath gd intl
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
COPY composer.json ./
COPY composer.loc[k] ./ 
RUN composer install --no-interaction --optimize-autoloader --no-dev --no-scripts --ignore-platform-reqs
COPY . .

# === STAGE 3: Final Production Image ===
FROM php:8.3-fpm-alpine
WORKDIR /var/www
RUN apk add --no-cache libzip libpng libjpeg-turbo freetype bcmath icu-libs curl \
    && apk add --no-cache --virtual .build-deps libzip-dev libpng-dev libjpeg-turbo-dev freetype-dev icu-dev curl-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install zip pdo_mysql bcmath gd intl \
    && apk del .build-deps
COPY --from=backend-builder /var/www /var/www
COPY --from=frontend-builder /app/public/build /var/www/public/build
RUN chown -R www-data:www-data /var/www/storage /var/www/bootstrap/cache
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
EXPOSE 8080
CMD ["php-fpm"]
```

### 2. `docker-compose.yml`

```yaml theme={null}
services:
  app:
    build:
      context: .
      target: backend-builder
    container_name: sitestore-app
    restart: unless-stopped
    environment:
      SERVICE_NAME: app
      DB_HOST: mysql
      REDIS_HOST: redis
    volumes:
      - .:/var/www
    networks:
      - sitestore-network

  queue-worker:
    build:
      context: .
      target: backend-builder
    container_name: sitestore-worker
    restart: unless-stopped
    command: php /var/www/artisan queue:work --verbose --tries=3 --timeout=90
    environment:
      SERVICE_NAME: queue-worker
      DB_HOST: mysql
      REDIS_HOST: redis
    volumes:
      - .:/var/www
    depends_on:
      - app
      - mysql
      - redis
    networks:
      - sitestore-network

  webserver:
    image: nginx:alpine
    container_name: sitestore-webserver
    restart: unless-stopped
    ports:
      - "8000:80"
    volumes:
      - .:/var/www
      - ./docker/nginx:/etc/nginx/conf.d/
    depends_on:
      - app
    networks:
      - sitestore-network

  mysql:
    image: mysql:8.0
    container_name: sitestore-db
    restart: unless-stopped
    ports:
      - "3306:3306"
    environment:
      MYSQL_DATABASE: sitestore_db
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_USER: sitestore_user
      MYSQL_PASSWORD: user_password
    volumes:
      - dbdata:/var/lib/mysql
    networks:
      - sitestore-network

  redis:
    image: redis:alpine
    container_name: sitestore-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    networks:
      - sitestore-network

networks:
  sitestore-network:
    driver: bridge

volumes:
  dbdata:
    driver: local
```

### 3. `docker/nginx/default.conf`

```nginx theme={null}
server {
    listen 80;
    index index.php index.html;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/public;
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\..+)($);
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
    location / {
        try_files $uri $uri/ /index.php?$query_string;
        gzip_static on;
    }
}
```

***

## Step 4: Configure Your Local `.env`

Open your local `.env` file and verify that the core connection strings map correctly to Docker's internal container routing network.

### CRITICAL SECURITY WARNING

The values listed below (such as `sitestore_db`, `root_password`, and `user_password`) match the default variables provided in the `docker-compose.yml` file. **These configurations are provided for local development example purposes only.**

You must change these credentials to unique, secure strings for your specific install. Never use these default passwords in a production environment or any public-facing server.

```ini theme={null}
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
# Change these values for safety:
DB_DATABASE=sitestore_db
DB_USERNAME=sitestore_user
DB_PASSWORD=user_password

# Redis Client & Container Routing:
REDIS_CLIENT=predis
REDIS_HOST=redis
REDIS_PORT=6379

CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
```

***

## Step 5: Start and Seed the Architecture

1. Verify that your Docker Desktop software dashboard status icon shows that the engine is active and running.
2. Clear out any stale, broken, or cached Docker build layers to guarantee a fresh initialization:
   ```bash theme={null}
   docker builder prune -f
   ```
3. Execute the compilation script in your project root terminal folder:
   ```bash theme={null}
   docker compose up -d --build
   ```
4. Install `predis` package inside the container (enables Redis caching, sessions, and queue support without requiring native PHP C-extensions):
   ```bash theme={null}
   docker compose exec app composer require predis/predis
   ```
5. Run the application core encryption algorithms and core database schemas:
   ```bash theme={null}
   docker compose exec app php artisan key:generate
   docker compose exec app php artisan migrate --seed
   ```
6. **(Optional) Load Developer QA Seed Data**\
   If you want to install a demo storefront populated with sample products, variants, categories, brands, testimonials, slideshows, digital downloads, and 24 sample product reviews, execute the target class seeder inside the running container:
   ```bash theme={null}
   docker compose exec app php artisan db:seed --class=DemoStoreSeeder
   ```
7. Access your running environment in your local web browser: **`http://localhost:8000`**

***

## Step 6: Default Admin Login

After running migrations and seeding, your Site Store Pro installation includes a default administrator account for initial access:

| Field        | Value                         |
| ------------ | ----------------------------- |
| **URL**      | `http://localhost:8000/admin` |
| **Email**    | `admin@support.local`         |
| **Password** | `SampleUser12345#`            |

### Warning

Change the default admin password immediately after your first login, especially before deploying to any publicly accessible or staging environment.

To change the temporary password:

1. Navigate to the admin dashboard panels.
2. Click on the **Top Right Green Dot** (positioned next to the Light/Dark Mode toggle icon).
3. Click on **'My Profile'** from the dropdown menu to set a secure password.

***

## Step 7: Environment Lifecycle Commands

* **Stop the environment (preserves data):** `docker compose down`
* **Wipe the database volume to start fresh:** `docker compose down -v`
* **Tail active runtime system error logs:** `docker compose logs -f`

***

## Server Configuration & Troubleshooting

### 1. Directory Permissions & `tempnam()` Errors

If you see the following notice or exception:

```
tempnam(): file created in the system's temporary directory
```

This error occurs when PHP attempts to create temporary compiled Blade view files in `storage/framework/views` (or session/cache files) and finds that the directory either **does not exist** or is **not writable** by the web server process.

<Tabs>
  <Tab title="AWS EC2 / ECS (Amazon Linux - ec2-user:apache)">
    ```bash theme={null}
    # 1. Create missing directories
    mkdir -p storage/framework/{cache/data,sessions,views,testing} storage/logs bootstrap/cache

    # 2. Assign ownership to ec2-user and apache group
    sudo chown -R ec2-user:apache storage bootstrap/cache

    # 3. Apply read/write/execute permissions and group inheritance (SetGID 2775)
    sudo chmod -R 2775 storage bootstrap/cache

    # 4. Clear cached views and config
    php artisan view:clear && php artisan config:clear
    ```
  </Tab>

  <Tab title="Ubuntu / Debian (Nginx or Apache - www-data)">
    ```bash theme={null}
    mkdir -p storage/framework/{cache/data,sessions,views,testing} storage/logs bootstrap/cache
    sudo chown -R www-data:www-data storage bootstrap/cache
    sudo chmod -R 775 storage bootstrap/cache
    php artisan view:clear && php artisan config:clear
    ```
  </Tab>

  <Tab title="cPanel / Shared Hosting">
    Ensure both `storage` and `bootstrap/cache` are created and set to permissions `775` (or `755`) via the cPanel File Manager or terminal, then run:

    ```bash theme={null}
    php artisan view:clear
    php artisan config:clear
    ```
  </Tab>
</Tabs>

***

### 2. Redis Configuration & "Class Redis not found"

Laravel defaults to the **`phpredis`** connector (`PhpRedisConnector`), which requires the native PHP C-extension (`ext-redis`). If your server or Docker container does not have this extension enabled, switching to Redis for caching and sessions will result in:

```
Class "Redis" not found (PhpRedisConnector.php:82)
```

#### Recommended Fix: Use `predis` (Pure PHP Driver)

`predis` runs entirely in userland PHP and requires no external `.dll` or `.so` extensions:

1. **Install `predis`:**
   * **Local / Dedicated Server / AWS EC2:**
     ```bash theme={null}
     composer require predis/predis
     ```
   * **Docker Container:**
     ```bash theme={null}
     docker compose exec app composer require predis/predis
     ```

2. **Configure `.env`:**
   ```dotenv theme={null}
   REDIS_CLIENT=predis
   CACHE_STORE=redis
   SESSION_DRIVER=redis
   QUEUE_CONNECTION=redis
   ```

3. **Clear configuration cache:**
   ```bash theme={null}
   php artisan config:clear
   # (Or inside Docker):
   docker compose exec app php artisan config:clear
   ```

#### Alternative: Enable Native `phpredis` C-Extension

If you prefer the native C-extension:

* **Windows**: Add `extension=php_redis.dll` (or `extension=redis`) to `php.ini` and restart web server.
* **Linux (Amazon Linux / RHEL)**: Install via `sudo pecl install redis` or `sudo dnf install php-pecl-redis`.
* **Linux (Ubuntu / Debian)**: Install via `sudo apt-get install php-redis`.
* **Set `.env`**: `REDIS_CLIENT=phpredis`.