Skip to content

Development Environment

Jump to bottom
Massimo edited this page Jul 12, 2022 · 6 revisions

Installation

If you lack a development environment all together, the following instructions will guide you through all the steps you need to take to be able to run a Javascript + Composer / PHP project locally.

Windows Subsystem for Linux (WSL)

This project runs best in WSL, so if you're on windows, you'll want to enable this feature. You can find more comprehensive instructions for doing that here. But for completeness, here is a summary:

Notice: Make sure windows is up to date before starting this. You may also need to enable Virtualization in your BIOS

  1. Open a power shell window and run dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  2. in the same power shell window run dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart, Then restart your machine.
  3. Download the latest WSL2 updates here, and install them.
  4. Back in the power shell run wsl --set-default-version 2
  5. Open the Microsoft store, then navigate to the Ubuntu 20.04 page, and click "get".
  6. Once installed, launch the Ubuntu 20.04 App from the start menu and follow the account set-up instructions. Make sure to pick a memorable sudo password.

After completing the above steps, you should now have an Ubuntu terminal that you can run the rest of the installation in.

Brew (MacOS only)

MacOS lacks a native package manager. If you haven't already you'll want to install brew.

To install brew, in a terminal, simply run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Once it completes, you can continue with the installation instructions.

PHP

First you'll need PHP running on your command line. To do this install it, as well as some of its dependencies.

For MacOS run:

brew install [email protected]
brew unlink php && brew link php

For WSL / Ubuntu run:

sudo apt install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.0-cli php8.0-mbstring php8.0-xml unzip php8.0-zip php8.0-mysql php8.0-curl php8.0-gd

Test:

# Test PHP is installed
php -v
# Check that PHP has the correct modules loaded
# The list should contain at the minimum mbstring, mysql, xml, and zip, more is fine
php -m

Composer

Next you'll need Composer; it manages all the PHP dependencies for the project, and installs the framework and vendor files.

On either WSL, Ubuntu, MacOS, run the following commands:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

Node

You'll also need node to build the front end, as well as mange the dependencies there as well. It is highly recommended that you use NVM that way you can manage different versions of node going forward.

On either WSL, Ubuntu, MacOS, run the following commands:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
## You'll probably need to restart your terminal before running the following 2 commands.
nvm install 14
nvm alias default 14

Yarn

You'll also likely need Yarn, it's generally consided a superior package bundler than NPM.

Yarn is a Javascript package manager for your code. It allows you to use and share code with other developers from around the world. Yarn does this quickly, securely, and reliably so you don’t ever have to worry.

Yarn allows you to use other developers’ solutions to different problems, making it easier for you to develop your software. If you have problems, you can report issues or contribute back, and when the problem is fixed, you can use Yarn to keep it all up to date.

Code is shared through something called a package (sometimes referred to as a module). A package contains all the code being shared as well as a package.json file which describes the package.

Simply run:

npm i -g yarn

After installing yarn, simply clone the repository and type yarn install at the project directory terminal and let it run When dependency installation is completed, yarn dev will build the app in public/js/app.js

Congratulation, you have completed front-end installation.

Docker

This project runs on a set of bespoke docker containers, controllable via docker compose. See the "Usage" section in the ReadMe for how to use docker compose with this project.

Before getting started though, you'll need to at least install Docker for the system you are currently running on.

Note: if you're on WSL / Windows you'll need to make sure that Docker is set up to pass through commands from WSL. Open the docker desktop application, go-to the Settings, and make sure the WSL checkbox is ticked under "resources"

Project Setup

Finally, you'll need an .env file, the project includes an .env.example file for reference. Copy the example file and rename it to .env, the default values of the example files are the ones expected by Sail (see below) If you are opting to use some other local environment, you'll need to set the appropriate values.

You'll also need to install the PHP dependencies, and set an application ID, this can be achieved by Laravel's command line utility, Artisan.

Lastly you'll need to install and build the front end as well. From the root of the project directory on you command line you can simply run:

cp .env.example .env

# nb: it's a helpful first step to run the following 4 commands every time you pull in new changes
composer install
php artisan migrate
yarn install
yarn dev

php artisan key:generate

Usage

Once all the above steps have been taken, it all you need to do is start the docker container stack and visit the site in your browser by running:

docker compose up -d

And then visit https://localhost

Clone this wiki locally