Skip to content

Setup

Jump to bottom
Vik Vanderlinden edited this page Dec 31, 2020 · 8 revisions

Following are the steps for the project-setup (all commands are run from the root directory):

This document will go over:

  • Docker installation
    • Basics
    • Using Laravel Sail
  • Manual Installation
  • Troubleshooting

Docker installation

Look at the requirements to run this back-end before running this. Windows users have to use WSL2.

Basics

  • Clone the repo: git clone https://www.github.com/iw-dbti-2016/columbo-backend.git INSIDE WSL!.
  • Navigate into the project-directory: cd ./columbo-backend.
  • Create a .env file in the root directory and configure the required keys for this application (redis, mysql credentials). The .env.example can be used as an example to fill in the required keys. Make sure to keep the mysql host and redis host in ./.env set to the values in ./.env.example.
  • [Optionally] For testing add a .env.testing with the required keys. Preferably create a new database for testing, because the RefreshDatabase trait is used in the PHPUnit tests.
  • Run the following script to install the composer dependencies (including laravel sail):
docker run --rm \
    -v $(pwd):/opt \
    -w /opt \
    laravelsail/php80-composer:latest \
    composer install

Using Laravel Sail

Every time:

  • [VS Code] Click the >< button at the lower left corner and select the 'Reopen folder in WSL' option. WSL will be connected to VS Code.
  • [VS Code] Open the terminal View > Terminal.
  • Run source .commands. This file holds an alias to the sail executable.
  • Run sail up -d.

First time only:

  • Run sail composer install.
  • Run sail npm install.
  • Run sail npm run dev.
  • Run sail artisan key:generate.
  • Run sail artisan storage:link.
  • Run sail artisan migrate.
  • Run sail artisan db:seed.
  • Run sail artisan telescope:publish.

After every pull:

  • Run sail composer install.
  • Run sail npm install.
  • Run sail npm run dev.

Always usable:

  • All commands can be run from the shell, which is accessible by running sail shell.
  • Run sail down to stop the system.
  • Running tests is possible by running sail test.

You are now ready to go, go to http://localhost:80/ !

Manual installation

First of all, make sure Composer, NPM, PHP (don't forget to enable the required extensions), MySQL and Redis are installed on your system. Look at the Requirements. A Google search can help you, this guide can help for Redis on windows 10.

Note that using Docker (see above) is recommended. The instructions below are not closely maintained, those for docker are.

  • Clone this repo: git clone https://www.github.com/iw-dbti-2016/columbo-backend.git.
  • Navigate into the project directory: cd ./columbo-backend.
  • Create a .env file in the root directory and configure the required keys for this application (redis, mysql credentials). The .env.example can be used as an example to fill in the required keys.
  • [Optionally] For testing add a .env.testing with the required keys. Preferably create a new database for testing, because the RefreshDatabase trait is used in the PHPUnit tests. More on tests below.
  • Run composer install.
  • Run npm install.
  • Run npm run dev.
  • Run php artisan key:generate to create a unique key for the application.
  • Run php artisan storage:link.
  • Create a database with the name as defined in your .env-file, default is columbo.
  • Run php artisan migrate.
  • Run php artisan db:seed.
  • Run php artisan telescope:publish.
  • Run php artisan serve.
  • Go to the browser, this application is now live on you machine.
  • [Optionally] You can run npm run watch when making changes to the resource-files (js/css).

For a production environment one would obviously run npm run production. Note that Laravel mix automatically adds versioning to the resource-files and uses purgeCSS to decrease the final css-file even further! Autoprefixer is always used, also in development. Thus no need to worry about this.

Following are the steps for running the tests:

  • Make sure you have a .env.testing-file in the root directory (next to the .env-file). This file can be identical to .env with the distinction that there should be a different database for running the tests. Our PHPUnit-tests use the RefreshDatabase trait extensively. This will refresh the database after each test. Refreshing the application database is not desirable, hence the seperate database.
  • From the root directory, run ./vendor/phpunit/phpunit/phpunit. This will run all tests. To filter to specific tests or files, use the --filter option.
Clone this wiki locally