Development Environment

To prepare the development environment, you will first need to choose how to deploy your application:

• If you use windows, you are recommended to make use of WSL2 and run Docker 'natively' on Linux (faster, easy).
• If you cannot use WSL2 on Windows, you are recommended to make use of a Virtual Machine running Linux (fast, easier).
• On native Linux you will get the best performance and support for tooling (fastest, easiest).

Minimum system requirements:

• approximately 20GB of disk space
• minimum of 4GB of RAM, 8GB recommended

Minimum required tools:

• apt

And after installation:

• docker
• docker compose (should come with the installation of docker)
• git
• make

Windows (WSL2)

1. Install Ubuntu on WSL2 as described here.
2. Follow the steps under Linux.

As WSL does currently not provide support for GUIs you may want to use Windows applications to edit the files. WSL exposes its files to Windows under \\wsl$\Ubuntu\ (a network location), which you can easily specify in PhpStorm or your preferred IDE.

It is also possible to use Docker for Windows, however, this comes with a severe performance hit and is not recommended.

Windows (Virtual Machine)

1. Install VirtualBox on your device. You can also use Hyper-V or an other alternative if you know how to use it.
2. Download an .iso image for Ubuntu or your favorite Linux distribution of choice.
3. Create a new Virtual Machine using the image you downloaded.
4. It is recommended (but optional) to enable VirtualBox Guest Additions

You can now follow the rest of the steps under Linux.

Linux

Assuming you use Ubuntu, the steps are as follows:

1. Update all packages by running sudo apt update && sudo apt upgrade
2. Install Docker Engine for Ubuntu as described here.
   • If you are using Ubuntu >22.* you may need to fix legacy iptables:

     sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
     sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
     

3. You must enable Docker BuildKit for better performance while building images as described here (the second permanent option is preferred).
4. It is recommended (but optional) to add yourself to the Docker user group by running sudo usermod -aG docker <username>. This way you don't have to insert sudo in front of all commands using Docker.
5. Run sudo apt install make git
6. Clone this repository: git clone [email protected]:gewis/gewisweb.git *.

The Docker daemon is not always active on a fresh startup, you can enable it via sudo service docker start.

*: It is recommended you use SSH keys to connect to GitHub, read more about how to use SSH keys with GitHub here.

If you use any other Linux distribution, we trust you know how to use it.

Further Installation Steps

To actually use the website you have to build the Docker container(s), see the Docker Deployment page for more details on how to do this. Afterwards, you should be able to access the website through http://localhost.

For editing project files, a good IDE is very helpful as it can provide hints while typing.

We recommend to use PhpStorm as an IDE and note that you are able to get a free professional license using your @student.tue.nl email address. You will need to renew this license yearly.

If you are unfamiliar with Git, you can use GitKraken or any other Git client which provides an easy-to-use user interface.

To get an optimal development experience, you can install additional tools that can aid the process. Read more about that on the Development aids page.