Local Development (Arch Linux)

UNIT3D v8.x.x on Arch Linux with Laravel Sail and PhpStorm

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.

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:

1. 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

Prerequisites

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.

Installing Docker and Docker Compose

Install Docker and Docker Compose:

sudo pacman -S docker docker-compose

Step 1: Clone the Repository

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

Step 2: Docker Environment Initialization

Switch to the project's root directory:

cd ~/PhpstormProjects/UNIT3D-Community-Edition

Switch to Branch 8.x.x

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

Step 3: Composer Dependency Installation

Verify Composer's presence on your system. Within the project folder, install PHP dependencies:

./vendor/bin/sail composer install

Step 4: App Key Generation

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.

Step 5: 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 6: Database Preparation

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 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.

Step 7: NPM Dependency Management

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

Step 8: Application Cache Configuration

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

sail artisan set:all_cache

Step 9: Environment Restart

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

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.

Docker Management

• 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.

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 NPM 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.