UNIT3D v8.x.x on MacOS with Laravel Sail and PhpStorm

A guide by HDVinnie

This guide is designed for setting up UNIT3D, a Laravel application, leveraging Laravel Sail on MacOS.

Warning: This setup guide is intended for local development environments only and is not suitable for production deployment.

Modifying .env and secure headers for non-HTTPS instances

For local development, it's common to use HTTP instead of HTTPS. To prevent mixed content issues, follow these steps:

Modify the .env config:
- Open your .env file located in the root directory of your UNIT3D project.
- Find the SESSION_SECURE_COOKIE setting and change its value to false. This action disables secure cookies, which are otherwise required for HTTPS.
```
SESSION_SECURE_COOKIE=false
```
Adjust the secure headers in config/secure-headers.php:
- Navigate to the config directory and open the secure-headers.php file.
- To disable the Strict-Transport-Security header, locate the hsts setting and change its value to false.
```
'hsts' => false,
```
- Next, locate the Content Security Policy (CSP) configuration to adjust it for HTTP. Disable the CSP to prevent it from blocking content that doesn't meet the HTTPS security requirements.
```
'enable' => env('CSP_ENABLED', false),
```

Prerequisites

Installing Docker Desktop

Install Docker Desktop

Once installed, launch Docker Desktop

Installing GitHub Desktop

Install GitHub Desktop

Once installed, launch GitHub Desktop

Installing PHPStorm

Install PHPStorm

Once installed, launch PHPStorm

Firstly, clone the UNIT3D repository to your local environment by visiting UNIT3D-Community-Edition Repo. Then click the blue colored code button and select Open with Github Desktop. Once Github Desktop is open set you local path to clone to like /Users/HDVinnie/Documents/Personal/UNIT3D-Community-Edition

Step 2: open the project in PHPStorm

Within PHPStorm goto File and then click Open. Select the local path you just did like /Users/HDVinnie/Documents/Personal/UNIT3D-Community-Edition.

The following commands are run in PHPStorm. Can do so by clicking `Tools->Run Command`.

Step 3: start Sail

Initialize the Docker environment using Laravel Sail:

./vendor/bin/sail up -d

Step 4: Composer dependency installation

./vendor/bin/sail composer install

Step 5: Bun dependency install and compile assets

./vendor/bin/sail bun install

./vendor/bin/sail bun run build

Step 6: database migrations and seeders

For database initialization with sample data, apply migrations and seeders:

./vendor/bin/sail artisan migrate:fresh --seed

Caution: This operation will reset your database and seed it with default data. Exercise caution in production settings.

./vendor/bin/sail mysql -u root -p unit3d < prod-site-backup.sql

Note: For this to work properly you must set the APP_KEY value in your local .env file to match you prod APP_KEY value.

Step 8: application cache configuration

Optimize the application's performance by setting up the cache:

sail artisan set:all_cache

Step 9: visit local instance

Open your browser and visit localhost. Enjoy!

Additional notes

Permissions: Exercise caution with sudo to avoid permission conflicts, particularly for Docker commands requiring elevated access.

Appendix: Sail commands for UNIT3D

This section outlines commands for managing and interacting with UNIT3D using Laravel Sail.

Sail management

Start environment:
```
./vendor/bin/sail up -d
```
Starts Docker containers in detached mode.
Stop environment:
```
./vendor/bin/sail down -v
```
Stops and removes Docker containers.
Restart environment:
```
./vendor/bin/sail restart
```
Applies changes by restarting Docker environment.

Dependency management

Install Composer dependencies:
```
./vendor/bin/sail composer install
```
Installs PHP dependencies defined in composer.json.
Update Composer dependencies:
```
./vendor/bin/sail composer update
```
Updates PHP dependencies defined in composer.json.

Laravel Artisan

Run migrations:
```
./vendor/bin/sail artisan migrate
```
Executes database migrations.
Seed database:
```
./vendor/bin/sail artisan db:seed
```
Seeds database with predefined data.

Refresh database:

./vendor/bin/sail artisan migrate:fresh --seed

Resets and seeds database.

Cache configurations:
```
./vendor/bin/sail artisan set:all_cache
```
Clears and caches configurations for performance.

NPM and assets

Install Bun dependencies:
```
./vendor/bin/sail bun install
```
Installs Node.js dependencies.
Compile assets:
```
./vendor/bin/sail bun run build
```
Compiles CSS and JavaScript assets.

Database operations

MySQL interaction:
```
./vendor/bin/sail mysql -u root -p
```
Opens MySQL CLI for database interaction.

Queue management

Restart queue workers:
```
./vendor/bin/sail artisan queue:restart
```
Restarts queue workers after changes.

Troubleshooting

View logs:
```
./vendor/bin/sail logs
```
Displays Docker container logs.
PHPUnit (PEST) tests:
```
./vendor/bin/sail artisan test
```
Runs PEST tests for application.

UNIT3D Documentation