Since Docker relies on the real Linux kernel virtualization provided by WSL 2 to run containers on Windows,
all related procedures are covered before moving forward with processes involving external applications.

Enabling Virtualization (VT-x/AMD-V) in the BIOS/UEFI interface is mandatory for WSL 2 because it relies on virtualization technology to run the Linux kernel.
Without it, WSL 2 will fail to start, restricting the system to WSL 1 or leading to error messages.
Although WSL 1 can function without this, enabling virtualization ensures compatibility with WSL 2 for better performance and features.

_{NOTE: The BIOS/UEFI interface is independent of the operating system and won't be affected by formatting the computer.}

1. Restart your computer and press the relevant BIOS/UEFI interface key.

2. During startup, press the BIOS/UEFI interface key (typically Delete, F2, F10, or F1, depending on your motherboard/brand).

3. Once in the BIOS/UEFI interface, navigate to the Advanced or CPU Configuration settings (this varies by manufacturer).

4. Look for an option called Intel VT-x (for Intel) or AMD-V (for AMD) and enable it.

5. Save your changes and exit the BIOS/UEFI interface (usually by pressing F10 and confirming).

   _{After rebooting, virtualization will be enabled.}

WSL enables the feature that allows Linux to run on Windows.
You'll need a Linux distribution to access the command line, where the kernel (the operating system's core) operates.

1. Open Windows Terminal (PowerShell or Command Prompt) as administrator (and leave it open for subsequent steps). (TODO: TEST STEPS IN POWERSHELL)

2. Install WSL:

   For this setup, where only CLI access is needed, Debian is a good lightweight option with standard features. #
   It's minimal, fast, and consumes fewer resources, perfect for just using WSL features without needing a full OS.

   Run the following streamlined command: #

   wsl --install --distribution Debian
   

   _{At the end of this step, you'll be prompted to create your UNIX user.}

3. Set default distribution for WSL:

   • WSL integration

     Set Debian (or desired distro) as the default.

     wsl --setdefault Debian
     

     _{This ensures that Docker Desktop does not override the default distro with its own. #}

Many commands require sudo access to install packages.
Completing the procedure below allows these commands to run without needing a password.

Extensions:

• Remote Explorer
• Dev Containers

  _{Although Docker's official extension remains a solid option, the combination above offers greater flexibility in the long run.}

Docker is a platform for building, shipping, and running applications in containers.

Docker containers create isolated environments, allowing applications to run with all dependencies and configurations encapsulated.

The Docker setup and environment configuration aims to keep both parts of the application functioning smoothly together, with Docker containers separating Laravel and Next.js environments for flexibility and ease of deployment.

• Key Concepts:

  • Containers: Lightweight, isolated environments that include everything needed to run an app.
  • Images: Read-only templates used to create containers. They can be shared via Docker Hub.
  • Volumes: Store persistent data that remains even after a container is deleted.

• Limits:

  • No fixed container limit, but resource use depends on your system (CPU, RAM).
  • Docker's free tier limits anonymous image pulls to 100 every 6 hours.

1. Enabling WSL 2 is a prerequisite to use Docker's Linux kernel environment for containerization on Windows (covered in the Setup section). # · #

2. Create a directory to store configuration files and data for the virtualized containers, ensuring both docker-compose.yml and Dockerfile are placed in it, as these will be used to set up the containers.

   docker-compose.yml

   
   

   Next, define the services you intend to use within the docker-compose.yml file.

   _{Each container_name must be unique.}

   version: '3.9'  # Optional, used for backward compatibility

   services:
     php-apache:  # PHP and Apache web server
       container_name: php-apache  # Name of the container
       build: .  # Build using the Dockerfile in the current directory
       volumes:
         - ./src:/var/www/html  # Map local `src` to `/var/www/html` in the container
       ports:
         - 8080:80  # Expose container port 80 on host port 8080
     db:  # MySQL database
       container_name: db  # Name of the container
       image: mysql:latest  # Use the latest MySQL image
       environment:
         MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}  # Set MySQL root password
         MYSQL_USER: webuser  # Create MySQL user `webuser`
         MYSQL_PASSWORD: ${MYSQL_PASSWORD}  # Password for `webuser`
       volumes:
         - ./db-data:/var/lib/mysql  # Persist database data
       ports:
         - 3306:3306  # Expose MySQL port
     phpmyadmin_global:  # phpMyAdmin for remote database access
       container_name: phpmyadmin_global  # Name of the container
       image: phpmyadmin/phpmyadmin:latest  # Use the latest phpMyAdmin image
       platform: linux/amd64  # Specify platform architecture
       environment:
         PMA_HOST: ${PMA_HOST}  # Remote database host
         PMA_USER: webuser  # Database user
         PMA_PASSWORD: ${PMA_PASSWORD}  # Password for `webuser`
         PMA_PORT: 3306  # Database port
       ports:
         - 8078:80  # Expose container port 80 on host port 8078
     phpmyadmin_local:  # phpMyAdmin for local database access
       container_name: phpmyadmin_local  # Name of the container
       image: phpmyadmin/phpmyadmin:latest  # Use the latest phpMyAdmin image
       platform: linux/amd64  # Specify platform architecture
       environment:
         PMA_HOST: db  # Connect to the `db` service
         PMA_USER: webuser  # Database user
         PMA_PASSWORD: ${PMA_PASSWORD}  # Password for `webuser`
         PMA_PORT: 3306  # Database port
       ports:
         - 8079:80  # Expose container port 80 on host port 8079
       depends_on:
         - db  # This service depends on `db`

   docker-compose.yml -> defines services, networks, and volumes for a multi-container docker application, allowing you to manage multiple containers as a single application.
   _{NOTE: In YAML files (like docker-compose.yml), a hyphen indicates an item in a list.}

   
   

   _{When you run docker-compose.yml, each service (such as php-apache, db, phpmyadmin) is started as an individual container,
   and they are grouped together under a label based on the folder name where docker-compose.yml is located.}

   Dockerfile

   
   

   As previously mentioned, use the Dockerfile for the php-apache service to add dependencies and properly configure the container.

   # Base image for the PHP and Apache environment
   FROM php:8.3-apache
   # FROM php:apache  # Pull the latest Apache version
   
   # Set the working directory for Apache
   WORKDIR /var/www/html
   
   # Update package lists and install required libraries for system utilities
   RUN apt update -y && \
       apt install -y libicu-dev unzip zip curl ca-certificates build-essential software-properties-common gnupg && \
       apt clean && \
       update-ca-certificates
   
   # Install Node.js, npm, and pnpm from NodeSource for the latest versions
   RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \
       apt update -y && \
       apt install -y nodejs && \
       npm install -g pnpm
   
   # Install PHP extensions for database and internationalization support
   RUN docker-php-ext-install gettext intl pdo_mysql mysqli && \
       docker-php-ext-enable mysqli
   
   # Copy Composer from its latest version image
   COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
   
   # Add Sass to the environment path for easy access
   ENV PATH=$PATH:/usr/local/dart-sass
   
   # Enable Apache's `mod_rewrite` module for URL rewriting
   RUN a2enmod rewrite
   
   # Install Sass for CSS preprocessing
   WORKDIR /usr/local
   ARG SASS_VERSION=1.74.1
   ARG SASS_URL="https://github.com/sass/dart-sass/releases/download/${SASS_VERSION}/dart-sass-${SASS_VERSION}-linux-x64.tar.gz"
   RUN curl -OL $SASS_URL && \
       tar -xzf dart-sass-${SASS_VERSION}-linux-x64.tar.gz && \
       rm -rf dart-sass-${SASS_VERSION}-linux-x64.tar.gz
   
   # Reset the working directory back to the default
   WORKDIR /var/www/html

   Dockerfile -> defines the instructions for building a Docker image, specifying the base image, environment setup and dependencies installation (which is our use case) and runtime configuration.

   
   

3. Once the files for building the images and containers are defined, run the command docker-compose up -d, where -d stands for "detached", meaning that it runs in the background (will not show any output from them in the console and run them in the background). #
   This command should be executed in the terminal from the directory where the previous files were placed.

   • First time run: Use the docker-compose up -d command.
   • Subsequent runs: You can start the container directly from the Docker Desktop interface.

   _{Run docker-compose build --no-cache whenever you've updated the Dockerfile or need to apply changes to the image.}

Laravel handles the backend (API, database interactions, and server-side functionality), while Next.js is taking care of the frontend.
This combination allows Laravel to serve as the API-only backend while Next.js builds the user interface with React.

1. If you haven't already, switch to VS Code.

   1. Open the Remote Explorer extension on the left, and ensure "Dev Containers" is selected in the dropdown at the top.
      

   2. In the "DEV CONTAINERS" section just below (visible due to the Dev Containers extension installed earlier), expand it to see a list of all containers.
      

   3. Select the php-apache container — this is the one used for working on the code.

      • To operate inside a container from the CLI, use the command docker exec -it {container_id} bash
        from the directory containing the Docker setup files. [OPTIONAL]

        _{Replace {container_id} with the ID of the container you want to access.}

      _{NOTE: When starting the php-apache container, it defaults to the var/www/html directory because this is set in docker-compose.yml.}

      
      

      ʀᴇꜰᴇʀᴇɴᴄᴇ:

      volumes:
        - ./src:/var/www/html

_{The following steps should be done in the root directory (the one named after the project).}

1. You can initialize a Laravel project with either:

   • The command composer create-project laravel/laravel <project_name>, if you want to start from scratch rather than a from the GitHub clone.

   • Or by cloning the repository from the CLI with git clone <repo-name> or (and the following will be the preferred method for this project):

     1. Go to the repo templates.
     2. Create a new project by clicking "Use this template" > "Create a new repository" (top right).
     3. Configuration/Settings:
        • Set it to "Private".
        • Under "Owner": "humanbit-dev-org".
        • Leave "Include all branches" unchecked.

2. Run composer install:

   composer install

3. Download the .env file from progetti aperti and paste it into the root directory.
   APP_URL and DB_DATABASE must be changed according to the project's configuration.

   _{NOTE: Make sure to re-add the initial dot, as Google Drive removes it.}

   • If you want to use the global database (shared), set the host to the server's IP.

   • If you want to use the local database (individual), set the host to the container name (in this case, db).

     ʀᴇꜰᴇʀᴇɴᴄᴇ

     
     

     docker-compose.yml

     db:
       container_name: db

     
     

     _{NOTE: If starting from scratch, run cp .env.example .env to copy the example configuration file and set the database parameters accordingly.}

4. Run this command to create a unique application key for security:

   php artisan key:generate

5. Next, run this command to create the tables in the database:

   php artisan migrate

   _{For table drop and recreation, run php artisan migrate:fresh.}

   _{For table drop, recreation and seeding, run php artisan migrate:fresh --seed.}

6. Finally, run this command to seed the database with sample data: [OPTIONAL]

   php artisan db:seed

   
   

   Note regarding steps 5 and 6 above:

   These operations should be performed only once during initial project setup,
   and then as needed for updates to Migrations, Factories, or Seeders.

   _{Global database (shared): This should be done by only one team member.}

   _{Local database (individual): This should be done by each individual team member.}

Backpack for Laravel is a tool to quickly set up and manage admin panels (CRUD interfaces) for database records in Laravel apps.

_{The following steps should be done in the root directory (the one named after the project).}

1. Inside Docker, the application runs on internal port 80, while the external port for accessing it is 8080.
   Temporarily update the .env file to match this setup:

   APP_URL=http://localhost:80/templates/public

   ʀᴇꜰᴇʀᴇɴᴄᴇ

   
   

   Placeholder.

   
   

2. Install Backpack for Laravel via Composer.

   composer require backpack/crud

3. Run the Backpack installation command and follow the prompts.

   php artisan backpack:install

4. Set the correct permissions for the storage directory.

   chmod -R 775 storage/
   chown -R www-data:www-data storage

5. Revert the .env file to use port 8080 like so:

   APP_URL=http://localhost:8080/templates/public

6. The admin panel will now be accessible at:

   http://localhost:8080/templates/public/admin
   

Follow these steps to set up and start the Next.js frontend within the container.
Make sure to execute these commands each time the container restarts:

1. Navigate to the frontend directory:

   Change into the frontend directory, where all the Next.js frontend code is located.

   cd frontend/

   Next.js telemetry management link.

2. Install dependencies with pnpm: [INITIAL INSTALL & DEPENDENCY UPDATES]

   Run pnpm install to ensure all project dependencies are installed.

   pnpm install

   • If you encounter an error due to missing pnpm, install it globally with:

     npm install -g pnpm

3. Start the development server:

   Run the Next.js development server, allowing you to view your application locally.

   pnpm dev

4. Compile Sass files:

   Sass and Prettier Watch

   
   

   Since this virtualized environment stores files on the host OS, file changes aren't detected on save.
   To force the container to capture these events:

   1. Copy the .prettierignore and .prettierrc.json files into the project directory.

   2. Install the necessary packages:

      pnpm install --save-dev prettier onchange @prettier/plugin-php concurrently

   3. In package.json, define the following script to watch both Prettier and Sass changes in parallel:

      "watch-all": "concurrently \"onchange \\\"../**/*\\\" --poll 1000 -- prettier --write --ignore-unknown {{changed}}\" \"sass --watch src/static/scss/:src/static/css/ --poll\""

   4. Run the combined watch script with:

      pnpm run watch-all

   This setup will simultaneously watch for changes in both Sass and Prettier, automatically compiling and formatting as needed.

   
   

   Start Sass in watch mode to automatically compile Sass files to CSS whenever changes are made.
   This command will keep the Sass compiler running and watching for changes in the assets/sass directory, outputting the CSS to assets/css.

   sass --watch src/static/scss/:src/static/css/ --poll

5. Adding packages, plugins, or libraries: [OPTIONAL]

   To install new packages, plugins, or libraries, use pnpm with the appropriate package name. For example:

   pnpm add <package-name>

This will add the package to the project and make it available for use within your Next.js application.

pnpm run build > build.log 2>&1

pnpm store prune && rm -rf .next node_modules pnpm-lock.yaml && pnpm install && pnpm run build

pnpm store prune && rm -rf .next node_modules pnpm-lock.yaml && pnpm install && pnpm run lint && pnpm run build

pnpm prettier --check ../**/* --ignore-path .prettierignore

php artisan cache:clear

php artisan config:clear

php artisan route:clear

1. Go to the repo templates.
2. Create a new project by clicking "Use this template" > "Create a new repository" (top right).
3. Configuration/Settings:
   • Set it to "Private".
   • Under "Owner": "humanbit-dev-org".
   • Leave "Include all branches" unchecked.

GitHub is arguably the most popular and fully-featured Git clients.

_{The hyperlinks in the following section contain a basic explanation upon hover.}

1. Local access

   • Use clone in GitHub Desktop to make the repository available locally if it's your first time with a new project.

     _{Operating locally allows each team member to develop independently without affecting the main project until changes are reviewed and merged.}

2. Work on your local installation

   • Continue coding and saving locally.
     After saving, you'll see both the old and new code side by side in GitHub Desktop, allowing you to compare the discrepancies from the cloned files to your changed ones.

3. Sync with the latest changes

   • If you're collaborating with other team members and need their latest adjustments before committing, perform fetch to check for updates:
     • If no variations are found after fetch, you're up-to-date.
     • If differences are found, you'll need to solve them so you can proceed to perform pull and integrate the latest changes into your local branch.

4. commit or stash your changes:

   • If you have unfinished tasks and need to switch branches or repositories, stash your modifications; otherwise, your progress will be lost.
   • Once you're ready, create a commit to save your local activity.

     _{Changes should always be committed in the local environment as doing so directly on GitHub website's interface may lead to conflicts or unintended errors.}
     

   • After committing, always fetch and pull to ensure you have the latest changes made by others and avoid conflicts.
     • If there are no conflicts, the changes will be merged automatically.
     • If conflicts occur, you'll need to resolve them manually.

5. push your changes to GitHub:

   • After committing, push your changes to the remote repository to make them available to other team members.
   • Applying specific commits from one branch to another can be achieved by cherry-picking.
   • Should any issues arise after changes are pushed and merged, GitHub allows you to rollback (reset/revert) and undo the changes.