UNIT3D Documentation

This guide outlines the process for setting up a local development environment using Laravel Sail, Docker Desktop, and PHPStorm.

Prerequisites

• Docker Desktop: Required to run the Sail containers.
• GitHub Desktop: Used to clone the repository.
• PHPStorm: Recommended IDE.

Installation Steps

1. Clone the repository: Use GitHub Desktop to clone the UNIT3D Repo.
2. Open in PHPStorm: Open the cloned directory in PHPStorm.
3. Start Sail: Initialize the Docker environment:

   ./vendor/bin/sail up -d

4. Install PHP dependencies:

   ./vendor/bin/sail composer install

5. Install Bun dependencies and build assets:

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

6. Initialize Database: Run migrations and seeders to populate the database with sample data:

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

7. Optimize Cache: Run the application cache configuration:

   ./vendor/bin/sail artisan set:all_cache

8. Access the app: Visit http://localhost in your browser.

To update UNIT3D, follow these steps to ensure data integrity and a smooth transition. Always review the release notes and check the new version's minimum requirements before starting.

1. Create a backup

Use UNIT3D's built-in backup system to create a complete backup of your environment before proceeding.

2. Enter maintenance mode

Put your application into maintenance mode to prevent users from accessing the site during the update:

cd /var/www/html
php artisan down

3. Run the update process

Use the git:update command to fetch the latest commits and stage them for installation. The process is interactive:

1. Start the update:

   cd /var/www/html
   php artisan git:update

2. Confirm steps: When prompted, choose yes to proceed with each step.
3. Accept upstream files: When prompted to overwrite local files (e.g., config/unit3d.php), type yes or press Enter to accept the default.
4. Run migrations: When prompted to run php artisan migrate, choose yes.
5. Install packages: When prompted to run composer install, choose yes.
6. Compile assets: When prompted to run bun run build, choose yes.

Follow these steps to automate the creation of a sanitized tarball containing your modified UNIT3D source code.

1. Create the script file:

   nano /var/www/html/create_tarball.sh

2. Add the generation logic: The script uses tar with an exclusion file, timestamps the filename, and creates a UNIT3D_Source_LATEST.tar.gz symlink in the public directory for easy access.

3. Make the script executable:

   chmod +x /var/www/html/create_tarball.sh

4. Run the script: Execute this whenever you update your site to generate a new tarball:

   /var/www/html/create_tarball.sh

#!/bin/bash

TARBALL_NAME="UNIT3D_Source_$(date +%Y%m%d_%H%M%S).tar.gz"
TAR_EXCLUDES="--exclude-from=/var/www/html/.tarball_exclude"

tar $TAR_EXCLUDES -czf /var/www/html/public/$TARBALL_NAME -C /var/www html

# Create a symlink to the latest tarball
ln -sf "/var/www/html/public/$TARBALL_NAME" "/var/www/html/public/UNIT3D_Source_LATEST.tar.gz"

If Redis is running on the same server as your web server, using Unix sockets instead of TCP ports can improve performance by up to 50%.

1. Prepare the socket directory and permissions:

sudo mkdir -p /var/run/redis/
sudo chown -R redis:www-data /var/run/redis
sudo usermod -aG redis www-data

2. Configure Redis: Add the following to your Redis configuration file (e.g., /etc/redis/redis.conf):

unixsocket /var/run/redis/redis.sock
unixsocketperm 770

3. Configure UNIT3D Environment Variables: Set the following in your .env file:

REDIS_HOST=/var/run/redis/redis.sock
REDIS_PORT=-1
REDIS_SCHEME=unix

4. Verify Database Config: Ensure config/database.php uses the REDIS_SCHEME variable in the options array:

'redis' => [
    'client' => env('REDIS_CLIENT', 'phpredis'),
    'options' => [
        'scheme' => env('REDIS_SCHEME', 'tcp'),
    ],
    // ...
],

5. Restart Redis:

sudo systemctl restart redis

Note: To connect via terminal using the socket, use: redis-cli -s /var/run/redis/redis.sock.

If MySQL is running on the same server as your web server, using Unix sockets can improve performance by up to 50%.

1. Configure MySQL: Open your MySQL configuration file (e.g., /etc/mysql/my.cnf) and update the [mysqld] section:

[mysqld]
user            = mysql
pid-file        = /var/run/mysqld/mysqld.pid
socket          = /var/run/mysqld/mysqld.sock
port            = 3306

2. Verify/Set Socket Permissions: Ensure the socket file exists in /var/run/mysqld/. If not, or if there are permission issues, run:

sudo chown mysql:mysql /var/run/mysqld/
sudo chmod -R 755 /var/run/mysqld/

3. Configure UNIT3D Environment Variables: Set the DB_SOCKET variable in your .env file to the path defined in your MySQL config:

DB_SOCKET=/var/run/mysqld/mysqld.sock

4. Apply Changes: Refresh the cache and restart services:

php artisan set:all_cache
sudo systemctl restart mysql && sudo systemctl restart php8.3-fpm && sudo systemctl restart nginx