-
Notifications
You must be signed in to change notification settings - Fork 17
Setup
These instructions will help setup the development environment using docker. It is also possible to run the environment without docker, however there are no instructions provided for that.
The following items are required when using these instructions.
- Docker
- If you are using Windows, you can download Docker Desktop for Windows here.
- Different instructions are needed for Windows 10 Home. Read these instructions here.
- If you are using a Mac, you can download Docker Desktop for Mac here.
- If you are using Linux, or using a virtual machine running Linux, you can read instructions on how to install Docker Engine on Ubuntu here.
- If you are using Windows, you can download Docker Desktop for Windows here.
It is recommended, but not neccessary, to install the following tools on your development environment. This makes your life easier.
- PHPStorm to make use of pre-configured Xdebug
- PHP >= 7.4 (older versions are not supported).
- Composer (http://getcomposer.org)
- NodeJS (https://nodejs.org)
- Yarn (https://yarnpkg.com)
For convenience sake the PHP container is able to run composer and yarn commands. However, it is often easier to run them outside of Docker.
First clone the repository.
git clone https://github.com/HUinstituteforICT/workplacelearning.git
After cloning, enter the project folder.
cd workplacelearning
Make a copy of the .env.example file, and name it .env.
If you want to use the development version of workplacelearning it is not necessary to configure the values inside.
cp .env.example .env
Now start the other containers with the following command below. Please note that running the application for the first time can take up to 30 minutes. This time could be better, or worse, dependent of your internet connection, processor, hard disk, etc.
docker-compose up -d
After the Docker environment is up and running, you need to install the PHP dependencies. This can be done through the PHP Docker container, or if you have Composer installed in your local development environment, you can use that by running composer install.
docker-compose exec php composer install
When the PHP dependencies are installed, you need to create the database schema. This is done by running the migrations with the following command.
# Yes, double php. First denotes container, second calls PHP executable
docker-compose exec php php artisan migrate:refresh --seed
The installation is almost finished. Run the following command to generate an encryption key.
docker-compose exec php php artisan key:generate
We're done.
You can now reach the following services:
| Service | Location |
|---|---|
| Webserver | localhost (HTTPS) |
| Database* | localhost:3306 |
| PhpMyAdmin* | localhost:8080 |
| Mailcatcher* | localhost:1080 |
*These services are only reachable in the development version.
The application itself enforces HTTPS (Secure HTTP). Please note that this is not the case for phpMyAdmin and Mailcatcher. If you need to reach these services, please make sure you are reaching those services by using HTTP (the insecure variant).
When registering a new account it might be necessary to increase the accounts rights to teacher or admin. This should be done through the PhpMyAdmin service. The login details of the database are found in the .env file (DB_USERNAME and DB_PASSWORD). When logged in, you can find a list of all user accounts in the student table. In this table, change the userlevel of the account you have registered to teacher (level 1) or admin (level 2). It is recommended to create in your local environment at least one admin account, one teacher account, and two student accounts (one for producing, one for acting). These four accounts will cover all functionality of the workplacelearning application.
As of August 2020 it is now mandatory to activate your workplacelearning account by email. In the local development environment, you can see all mail traffic generated by the workplacelearning application by browsing to the mailcatcher in your webbrowser.
If you get a "Permission denied" or HTTP 500 error when opening the webpage, make sure that the PHP Docker container has write access to the "bootstrap/cache" folder and the "storage" folder. You can do this by replacing the ownership of the two folders. The numbers "33" in the command below are the user ID and group ID for "www-data", the user/group used by PHP (in the Docker container).
chown 33:33 bootstrap/cache -R
chown 33:33 storage -R
At this moment, Javascript and CSS assets have compiled versions in the repository. This might change in the future. Javascript and CSS should be compiled after every asset update. Asset compilation can be done using Laravel Mix. These commands should only be run if these assets are changed.
This requires that the dependencies are installed, install them with:
docker-compose exec php yarn
Or if yarn is available on host machine use yarn
Now you can compile assets with
docker-compose exec php yarn dev
To keep compiling on changes
docker-compose exec php yarn watch
Tests can be ran in the IDE by configuring PHPUnit in it.
Alternatively you can execute it in the PHP container by running:
docker-compose exec php ./vendor/bin/phpunit
Please note that unit tests are currently untested and/or broken due to software upgrades.
It is possible that the workplacelearning environment gets broken. Most of the time this is caused by stale (old) Docker images. You can get rid of the old images by running the following three commands.
docker-compose down
docker image prune -a
docker system prune
After running these three commands, run the Docker environment by executing docker-compose up -d. This will take a while, because the new Docker images are being downloaded and built.