================================================================================
               SMARTBULLS BACKEND - LOCALHOST RUNNING & TESTING GUIDE
================================================================================

This document outlines the step-by-step checklist to easily configure, build, 
and run the entire SmartBulls backend stack locally on your computer (localhost).

--------------------------------------------------------------------------------
1. PREREQUISITES
--------------------------------------------------------------------------------
Before starting, ensure you have the following installed on your machine:
* Docker (Desktop or Server)
* Docker Compose

--------------------------------------------------------------------------------
2. ENVIRONMENT SECRETS SETUP (.env)
--------------------------------------------------------------------------------
By default, the `docker-compose.yml` mounts the secure configurations directory from:
`/var/www/secure`

On your local machine, you must create this directory and add the `.env` file:

[Step 2.1] Create the secure directory:
           $ sudo mkdir -p /var/www/secure
           $ sudo chmod 777 /var/www/secure

[Step 2.2] Create a `.env` file inside `/var/www/secure/.env` and define:


--------------------------------------------------------------------------------
3. LOCAL DNS MAPPING (THE PREMIUM ROUTE)
--------------------------------------------------------------------------------
To test SSL, notifications, and webhooks locally without modifying Nginx config or 
getting certificate warning loops, map the staging domain to your loopback address:

[Step 3.1] Open your host system's hosts file:
           - Linux/macOS: `/etc/hosts` (edit with sudo)
           - Windows: `C:\Windows\System32\drivers\etc\hosts` (edit as Administrator)

[Step 3.2] Append the following line:
           127.0.0.1  app.edistry.com

Now, navigating to `https://app.edistry.com` in your browser will route requests 
directly to your local docker container, resolving the staging SSL certificates perfectly!

--------------------------------------------------------------------------------
4. ACCESS DIRECTLY VIA LOCALHOST (THE DIRECT ROUTE)
--------------------------------------------------------------------------------
If you do not want to use hosts file mapping:
* Open Nginx in browser: `http://localhost` (Port 80)
* Web routing and API services will listen at:
  - Express API: `http://localhost:4000`
  - WebSockets: `http://localhost:5000`
  - PHP App: Routed automatically via Nginx

--------------------------------------------------------------------------------
5. STARTING THE STACK
--------------------------------------------------------------------------------
Navigate to the project root directory and execute:

# 1. Clean build and launch all containers
$ docker-compose up -d --build

# 2. Check running status
$ docker-compose ps

# 3. Follow system logs
$ docker-compose logs -f

--------------------------------------------------------------------------------
6. DATABASE ADMINISTRATION & PMA
--------------------------------------------------------------------------------
You can access phpMyAdmin locally to run queries, manage tables, or import logs:
* URL: `http://localhost:8888` (or `http://localhost:8081` depending on configuration)

================================================================================