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 tofalse
. This action disables secure cookies, which are otherwise required for HTTPS.
SESSION_SECURE_COOKIE=false
- Open your
-
Adjust the secure headers in
config/secure-headers.php
:- Navigate to the
config
directory and open thesecure-headers.php
file. - To disable the
Strict-Transport-Security
header, locate thehsts
setting and change its value tofalse
.
'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),
- Navigate to the
Prerequisites
Installing Docker Desktop
Once installed, launch Docker Desktop
Installing GitHub Desktop
Once installed, launch GitHub Desktop
Installing PHPStorm
Once installed, launch PHPStorm
Step 1: clone the repository
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.
Step 7: database preparation (if want to use a production database backup locally)
Initial database loading
Prepare your database with the initial schema and data. Ensure you have a database dump file,
e.g., prod-site-backup.sql
.
MySQL data importation
To import your database dump into MySQL within the local environment, use:
./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:
Opens MySQL CLI for database interaction../vendor/bin/sail mysql -u root -p
Queue management
- Restart queue workers:
Restarts queue workers after changes../vendor/bin/sail artisan queue:restart
Troubleshooting
-
View logs:
./vendor/bin/sail logs
Displays Docker container logs.
-
PHPUnit (PEST) tests:
./vendor/bin/sail artisan test
Runs PEST tests for application.