PROJECT SETUP

If assistance is needed, contact Kevin Noguera

PREREQUISITES

The following are the applications/ accounts required before installing project dependencies:

Ubuntu 22.04 LTS (from Microsoft Store)
Docker Desktop (latest)
Postman (for API development)
Visual Studio Code (latest)
Bitbucket Account (for repositories)

The following are packages/ libraries to install inside Ubuntu WSL:

PHP 8.2
Composer

sudo apt-get install composer

Node 18.0.0^
Git

// Update Ubuntu
sudo apt update

// Install Git
sudo apt install git

// Verify installation
git --version

STEPS

Make sure that the following are installed in your machine before continuing.
Open Docker Desktop and make sure its running.
Open Ubuntu 22.04 terminal
On the terminal, generate the SSH key to clone the repository

// To generate SSH key, run the command below (press continue until the process is done):
ssh-keygen

// Copy the key after running the command below
// and upload it on your Bitbucket account's personal settings for SSH keys
// File name may vary from id_rsa.pub if you change it on the prompt
cat ~/.ssh/id_rsa.pub

When getting the clone command, don't forget to select SSH
The clone command should be something like this:

git clone git@bitbucket.org:organization/repository.git

Copy your environment file by:
1. Duplicate .env.example to .env or running the command below (still inside your project folder)

Note:

Important step, do not skip
.env will be used by Docker when building images for our database (MySQL & phpMyAdmin), MailHog, and Redis
You might also need to rebuild the Docker container by removing related Images, Volumes, and Containers and running again the ./vendor/bin/sail up

cp .env.example .env
// or you can ask Kevin Noguera for the latest .env file

After cloning the project, you may customize your identity by running the following command inside the project folder:

// The following commands is used to update your name and email that will be shown
// in your commits
git config user.name "YOUR_NAME"
// Your email should be the same as your Bitbucket account
git config user.email "YOUR_EMAIL"

After updating your identity, install your project's PHP and Node dependencies:
1. If the command for migration and seed fails, please refer to this

// For installing PHP dependencies such as sail
composer install

// Building your project's docker container for the first time
./vendor/bin/sail up

// For first time use, run the migrations with seeder
// (includes initial organization, organization users, users and permission records)
./vendor/bin/sail php artisan migrate:fresh --seed

// If an error about permissions occur after running the command above
// run the command below:
// Also, go outside your project's folder for this
chmod -R 775 <folder or file e.g. project>

// For installing frontend dependencies such as vue, vee-validate etc.
./vendor/bin/sail npm --legacy-peer-deps ci

// For building your frontend files
npm run dev

If you run ./vendor/bin/sail up -d and message Docker is not running. shows up.
1. On Docker, go to Settings > Resources > WSL Integration
2. Enable your Ubuntu version, e.g. Ubuntu-22.04, then click Apply & Restart
To confirm successful setup, open the following in the browser:

// For the web app
https://localhost

// If https://localhost/login is not working and showing an apache page,
// run the following command:
sudo systemctl disable apache2 && sudo systemctl stop apache2

// To verify if the service is disabled
sudo systemctl status apache2

// For the phpmyadmin - database
https://localhost:8081

// For mailhog
https://localhost:8025

// If any of the above is not accessible, the port may have been changed
// please refer to docker-compose.yml

OTHERS

To limit/ adjust the memory usage of Docker:
1. Setup .wslconfig on %UserProfile% of windows machine to limit resources used by the virtual machine
2. For convenience on locating the folder, copy and paste %UserProfile% on the URL box of the file explorer
List of sail commands:
1. ./vendor/bin/sail up - for building your docker container for the first time
2. ./vendor/bin/sail down - for shutting down your docker container
3. ./vendor/bin/sail up -d - for running your built docker container without live logs
For convenience, you may setup alias to common commands on Ubuntu

// Setup bash alias on home directory on Ubuntu terminal
cd ~/

// When opening .bashrc, its recommended to put bash aliases on its own file ".bash_aliases"
nano .bash_aliases

// Add following alias i.e.
alias sup='./vendor/bin/sail up -d'
alias sd='./vendor/bin/sail down'
alias sw='./vendor/bin/sail npm run watch'
alias proj='cd project'
alias gdev='git checkout develop && git pull origin develop'
alias art='./vendor/bin/sail php artisan'

// To refresh the terminal for the alias to take effect
bash

If you cannot run the ./vendor/bin/sail php artisan migrate:fresh --seed , do the following:

// Open Docker Desktop
// Go to project directory
// Run the command below
docker-compose exec mysql bash
mysql -u root -p
GRANT ALL PRIVILEGES ON *.* TO '<sail-user-from-docker-compose-yml>'@'%';
FLUSH PRIVILEGES;

To import a database/ SQL dump without using PHPMyAdmin

// Find first the mysql container, make sure Docker Desktop is running
docker ps

// Copy the database dump to the Ubuntu home folder
// Run the following command:
// Note that the [DB_NAME]<"FILENAME.EXTENSION" may be bypassed by the
// SQL script on which database will the records be imported to
docker exec -i [MYSQL_CONTAINER_HASH] mysql -u[USERNAME] -p[PASSWORD] [DB_NAME]<"FILENAME.EXTENSION"

// The command should be something like this
docker exec -i 3482ced9e067 mysql -usail -ppassword betadb<"pocdb_2023-11-1.sql"

Other personal commands:

// Getting route list
php artisan route:list
// or with alias
art route:list

Related browser extensions:

Last updated 4 months ago