Unit3d Setup Guide

Windows Users: Enable WSL Integration

If you are using Windows, ensure that WSL integration is enabled in Docker Desktop for containers to work properly:

1. Open Docker Desktop.
2. Go to Settings > Resources > WSL Integration.
3. Enable integration for your desired WSL distributions (e.g., Ubuntu).

Enable Mirrored Networking Mode in WSL

To improve network compatibility for Docker containers on Windows, enable "mirrored" networking mode in WSL:

1. Open Docker Desktop.
2. Go to Settings > WSL > Networking.
3. Set Network Mode to Mirrored.

This ensures containers have better access to network resources and services.

This allows Docker containers to run seamlessly with WSL on Windows.

1. Confirm MySQL Host and Port

• If using Laravel Sail, set DB_HOST to mysql (the service name in docker-compose.yml), not 127.0.0.1.

• Example for Sail:

  DB_HOST=mysql
  

• Ensure your .env file has the correct Redis host configuration for Sail:

  REDIS_HOST=redis
  

• If you encounter "Connection refused", verify the Redis container is running:

  ./vendor/bin/sail ps
  ./vendor/bin/sail up -d redis
  

1. Install Docker and Docker Compose on Linux

Ubuntu/Debian

sudo apt update
sudo apt install -y docker.io docker-compose-v2

Arch Linux

sudo pacman -Syu
sudo pacman -S docker docker-compose

Enable and Start Docker

After installing Docker, enable and start the Docker service:

sudo systemctl enable docker
sudo systemctl start docker

2. Install PHP 8.4

Ubuntu

# Add the ondrej/php repository.
sudo apt update
sudo apt install -y software-properties-common
sudo LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php -y
sudo apt update

# Install PHP.
sudo apt-get install -y php8.4 php8.4-curl php8.4-zip php8.4-xml php8.4-bcmath php8.4-intl php8.4-mysql php8.4-redis php8.4-mbstring mariadb-client-core unzip

Debian

# Add the packages.sury.org/php repository.
sudo apt-get update
sudo apt-get install -y lsb-release ca-certificates apt-transport-https curl
sudo curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt-get update

# Install PHP.
sudo apt-get install -y php8.4 php8.4-curl php8.4-zip php8.4-xml php8.4-bcmath php8.4-intl php8.4-mysql php8.4-redis php8.4-mbstring mariadb-client-core unzip

Arch Linux

# Update system and install PHP with required extensions and Composer.
sudo pacman -Syu
sudo pacman -S php php-fpm php-gd php-intl php-pgsql php-sqlite php-redis php-imagick composer

3. Clone the UNIT3D Repository

git clone https://github.com/HDInnovations/UNIT3D.git
cd UNIT3D

4. Install Composer

Ubuntu/Debian

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f88543c636f7cd84f6db9189d43a81e5503cda447da73c7e5b6') { echo 'Installer verified'.PHP_EOL; } else { echo 'Installer corrupt'.PHP_EOL; unlink('composer-setup.php'); exit(1); }"
php composer-setup.php
php -r "unlink('composer-setup.php');"

sudo mv composer.phar /usr/local/bin/composer

Note: On Arch Linux, Composer is installed via pacman in the previous step and does not require manual installation.

5. Enable PHP Extensions

To enable required PHP extensions on Ubuntu, run:

sudo sed -i '/^;zend_extension=opcache/s/^;//' /etc/php/8.4/cli/php.ini \
    && sudo sed -i '/^;extension=iconv/s/^;//' /etc/php/8.4/cli/php.ini \
    && sudo sed -i '/^;extension=bcmath/s/^;//' /etc/php/8.4/cli/php.ini \
    && sudo sed -i '/^;extension=redis/s/^;//' /etc/php/8.4/cli/php.ini \
    && sudo sed -i '/^;extension=intl/s/^;//' /etc/php/8.4/cli/php.ini \
    && sudo sed -i '/^;extension=mysqli/s/^;//' /etc/php/8.4/cli/php.ini \
    && sudo sed -i '/^;extension=pdo_mysql/s/^;//' /etc/php/8.4/cli/php.ini

To enable required PHP extensions on Arch Linux, run:

sudo sed -i '/^;zend_extension=opcache/s/^;//' /etc/php/php.ini \
    && sudo sed -i '/^;extension=iconv/s/^;//' /etc/php/php.ini \
    && sudo sed -i '/^;extension=bcmath/s/^;//' /etc/php/php.ini \
    && sudo sed -i '/^;extension=redis/s/^;//' /etc/php/php.ini \
    && sudo sed -i '/^;extension=intl/s/^;//' /etc/php/php.ini \
    && sudo sed -i '/^;extension=mysqli/s/^;//' /etc/php/php.ini \
    && sudo sed -i '/^;extension=pdo_mysql/s/^;//' /etc/php/php.ini

Note: Adjust the path to php.ini if your PHP installation uses a different location

6. Copy the Environment File

After cloning the repository, copy the example environment file:

cp .env.example .env

7. Install Dependencies with Composer

Run the following commands inside the UNIT3D directory to install and update PHP dependencies:

composer update
composer install

8. Start UNIT3D with Laravel Sail

Before starting UNIT3D, add your user to the Docker group to run Docker commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

or Log out and back in for the group change to take effect.

9. To start the application using Laravel Sail, run:

./vendor/bin/sail up -d

This will start the required Docker containers in detached mode.

10. Generate Application Key

After starting the containers, generate the Laravel application key:

./vendor/bin/sail artisan key:generate

This command sets the APP_KEY value in your .env file, which is required for application security.

11. Run Database Migrations and Seed Data

To set up the database schema and seed initial data, run:

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

12. Manage Node.js Dependencies and Compile Assets

To install Node.js dependencies and build frontend assets within the Docker environment, run:

./vendor/bin/sail bun install
./vendor/bin/sail bun run build

If you need to refresh the Node.js environment (e.g., after updating dependencies), use:

./vendor/bin/sail rm -rf node_modules && bun pm cache rm && bun install && bun run build

13. Application Cache Configuration

Optimize performance by setting up the cache:

./vendor/bin/sail artisan set:all_cache

14. Environment Restart

Apply new configurations or restart the environment:

./vendor/bin/sail restart && ./vendor/bin/sail artisan queue:restart

---

Additional Notes

• Permissions: Use sudo cautiously to avoid permission conflicts, especially with Docker commands requiring elevated access.

---

Appendix: Sail Commands for UNIT3D

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 the Docker environment.

Dependency Management

• Install Composer dependencies:

  ./vendor/bin/sail composer install
  

  Installs PHP dependencies.

• Update Composer dependencies:

  ./vendor/bin/sail composer update
  

  Updates PHP dependencies.

Laravel Artisan

• Run migrations:

  ./vendor/bin/sail artisan migrate
  

  Executes database migrations.

• Seed database:

  ./vendor/bin/sail artisan db:seed
  

  Seeds the database.

• Refresh database:

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

  Resets and seeds the database.

• Cache configurations:

  ./vendor/bin/sail artisan set:all_cache
  

  Clears and caches configurations.

NPM and Assets

• Install Node.js 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.

Queue Management

• Restart queue workers:

  ./vendor/bin/sail artisan queue:restart
  

  Restarts queue workers.

Troubleshooting

• View logs:

  ./vendor/bin/sail logs
  

  Displays Docker container logs.

• Run PHPUnit (PEST) tests:

  ./vendor/bin/sail artisan test
  

  Runs PEST tests for the application.