UNIT3D-Guide/README.md

# Unit3d Setup Guide


## 1. Install Docker and Docker Compose on Linux
### Ubuntu/Debian
```bash
sudo apt update
sudo apt install -y docker.io docker-compose-v2
```


### Arch Linux
```bash
sudo pacman -Syu
sudo pacman -S docker docker-compose
```

# Enable and Start Docker

After installing Docker, enable and start the Docker service:

```bash
sudo systemctl enable docker
sudo systemctl start docker
```

## 2. Install PHP 8.4

### Ubuntu

```bash
# 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

```bash
# 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

```bash
# 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

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


## 4. Install Composer

### Ubuntu/Debian

```bash 
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:

```bash
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:

```bash
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:

```bash
cp .env.example .env
```

## 7. Install Dependencies with Composer

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

```bash
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`:

```bash
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:

```bash
./vendor/bin/sail up -d
```

> **Tip:** The MySQL container may need to be restarted multiple times during initial setup. If you encounter connection issues, run:
>
> ```bash
> ./vendor/bin/sail restart mysql
> ```
>
> Wait a few moments after each restart before retrying your commands.

This will start the required Docker containers in detached mode.

For troubleshooting MySQL root user errors, see [Fix MySQL root user error](./Troubleshooting.md#fix-mysql-root-user-error).


## 10. Generate Application Key

Before generating the Laravel application key, ensure your `.env` file contains an `APP_KEY` variable (it can be empty):

```bash
./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:

```bash
./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:

```bash
./vendor/bin/sail bun install
./vendor/bin/sail bun pm untrusted
./vendor/bin/sail bun pm trust --all
./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:

```bash
./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:

```bash
./vendor/bin/sail artisan set:all_cache
```

## 14. Environment Restart

Apply new configurations or restart the environment:

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

---