-
-
Notifications
You must be signed in to change notification settings - Fork 369
Local Development (Arch Linux)
A guide by EkoNesLeg
This guide is designed for setting up UNIT3D, a Laravel application, leveraging Laravel Sail on Arch Linux. The guide emphasises using Arch Linux as the OS and PhpStorm as the IDE, but the instructions are adaptable to other environments.
Warning: This setup guide is intended for local development environments only and is not suitable for production deployment.
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. -
Add/modify the following environment variables.
DB_USERNAME=unit3d # The username can be anything except `root` SESSION_SECURE_COOKIE=false # Disables secure cookies CSP_ENABLED=false # Disables Content Security Policy HSTS_ENABLED=false # Disables Strict Transport Security
-
Before beginning, you must have Docker and Docker Compose installed. These tools are fundamental for establishing and managing the Dockerized development environment facilitated by Laravel Sail.
Install Docker and Docker Compose:
sudo pacman -S docker docker-compose
Firstly, clone the UNIT3D repository to your local environment. Move to your chosen workspace directory:
cd ~/PhpstormProjects
Then, clone the repository with the following command:
git clone git@github.com:HDInnovations/UNIT3D-Community-Edition.git
Switch to the project's root directory:
cd ~/PhpstormProjects/UNIT3D-Community-Edition
Before starting Docker, switch to the 8.x.x
branch:
git checkout 8.x.x
Initialize the Docker environment using Laravel Sail:
./vendor/bin/sail up -d
Verify Composer's presence on your system. Within the project folder, install PHP dependencies:
./vendor/bin/sail composer install
Generate a new APP_KEY
in the .env
file to be used for encryption throughout the app:
./vendor/bin/sail artisan key:generate
Note: If importing a database backup, edit the APP_KEY
in the .env
file to match the same key used as when the backup was created.
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.
Prepare your database with the initial schema and data. Ensure you have a database dump file,
e.g., prod-site-backup.sql
.
To import your database dump into MySQL within the Docker environment, use:
./vendor/bin/sail mysql -u root -p unit3d < prod-site-backup.sql
Note: For better compatibility, ensure the APP_KEY value in the .env
file matches the one your deployment
environment.
Within the Docker environment, manage Node.js dependencies and compile assets:
./vendor/bin/sail bun install
./vendor/bin/sail bun run build
For refreshing the Node.js environment, if necessary:
./vendor/bin/sail rm -rf node_modules && bun pm cache rm && bun install && bun run build
Optimize the application's performance by setting up the cache:
sail artisan set:all_cache
To apply new configurations or simply restart the environment, toggle the Docker environment down and up:
./vendor/bin/sail restart && ./vendor/bin/sail artisan cache:optimize
-
Permissions: Exercise caution with
sudo
to avoid permission conflicts, particularly for Docker commands requiring elevated access.
This section outlines commands for managing and interacting with UNIT3D using Laravel Sail.
-
Start Environment:
./vendor/bin/sail up -d
Starts Docker containers in detached mode.
-
Stop Environment:
./vendor/bin/sail down
Stops and removes Docker containers.
-
Restart Environment:
./vendor/bin/sail restart
Applies changes by restarting Docker environment.
-
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
.
-
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.
-
Install NPM Dependencies:
./vendor/bin/sail bun install
Installs Node.js dependencies.
-
Compile Assets:
./vendor/bin/sail bun run build
Compiles CSS and JavaScript assets.
-
MySQL Interaction:
Opens MySQL CLI for database interaction.
./vendor/bin/sail mysql -u root -p
-
Restart Queue Workers:
Restarts queue workers after changes.
./vendor/bin/sail artisan queue:restart
-
View Logs:
./vendor/bin/sail logs
Displays Docker container logs.
-
PHPUnit (PEST) Tests:
./vendor/bin/sail artisan test
Runs PEST tests for application.