fhooe-webdev – A Vagrantfile and Vagrant Box for Web Development Classes

This repository provides a Vagrantfile for a consistent Linux-based web development environment designed for the use in web development classes at the Upper Austria University of Applied Sciences (FH Oberösterreich), Hagenberg Campus.

The Vagrantfile works with our own fhooe/fhooe-webdev box, which is based on Ubuntu 22.04 and includes Apache2, PHP 8.2, MariaDB 10.11, as well as additional tools and scripts.

Not familiar with Vagrant or not sure why to use it? Have a look at the Introduction first.

Installation of Software and Prerequisites

To use this environment, you will need VirtualBox and Vagrant. For them to work on your machine, make sure the following prerequisites are fulfilled:

• Virtualization is activated in BIOS.
• 10 GB of disk space is available locally. If possible, use an SSD for better performance.
• [Windows] At least VirtualBox 6.1.26 under Windows 10 21H1 or Hyper-V deactivated when using an earlier version. Version 7 and the latest version of Windows are recommended.
• [Mac OS X] Make sure VirtualBox has the necessary permissions. Go to "System Settings -> Security -> Allow Virtual Box".

Then install the required software in the following order:

1. Download the latest version of VirtualBox from https://www.virtualbox.org/wiki/Downloads and install it. Alternatively, when running Windows, use Chocolatey: choco install virtualbox.
2. Download the latest version of Vagrant from https://www.vagrantup.com/downloads.html and install it. With Chocolatey on Windows, run choco install vagrant.
3. Reboot your computer for all changes to take effect.

How to Use the Vagrantfile

1. Download or clone the fhooe-webdev repository to a location of your choice on your computer. If you don't want the whole repository, downloading the Vagrantfile will suffice.
2. Open PowerShell, a command prompt, or the terminal.
3. Switch to the directory where you cloned/downloaded the repository or Vagrantfile, e.g. cd <path-to>/fhooe-webdev.
4. Run vagrant up. This will download the fhooe/fhooe-webdev box (a fully configured Ubuntu image) from Vagrant Cloud, provision it, and run it without a GUI (headless mode).
5. Once the image has finished downloading and has started successfully, you can use vagrant ssh to connect to the image's shell via SSH.
6. To stop and shut down the image, call vagrant halt.
7. To destroy the image (in case you don't need it anymore or want it re-initialized), call vagrant destroy.

How to Use the Image for Web Development

Once the image has successfully been booted, you will notice that a folder called webapp inside your <path-to>/fhooe-webdev directory has been created. This directory is mapped to /var/www/html/webapp in the image via Vagrant's shared folder functionality. Since it points to Apache's document root, files are immediately served through the web server.

Additionally, the Vagrantfile configures the IP address 172.16.7.7 as a private network so you can access the machine and its web server under this address.

To develop and deploy your web applications, copy them to the webapp folder on your host machine. They will be instantly available through the Vagrant image's web server at 172.16.7.7. E.g.:

• webapp/my_example_project/index.php -> https://172.16.7.7/webapp/my_example_project/index.php

There's a file called phpinfo.php in the webapp directory that allows you to check the configuration of this image quickly. Also, phpMyAdmin is already installed and configured. These are available here:

• https://172.16.7.7/webapp/phpinfo.php
• https://172.167.7.7/phpmyadmin

The default configuration uses HTTPS and mimics a production web server without displaying any PHP errors. To work without HTTPS (thus avoiding the certificate warning), open your files with HTTP on port 81. E.g.:

• http://172.16.7.7:81/ for the dashboard or
• http://172.16.7.7:81/webapp/ for the webapp directory.

Since all the files of your web projects are on your host computer, you can destroy, remove or reset the Vagrant image at any time. Nothing within the webapp directory is affected.

Tips and Troubleshooting

• During the initial vagrant up, a stable internet connection for downloading the box file is required. Once the box has been downloaded, you can work offline.
• If the box hangs during booting at the SSH steps, you can disable the automatic SSH login and use a user/password combination instead. See the commented-out sections in the Vagrantfile for this.
• Another solution for a hanging box at startup is to launch the Oracle VM VirtualBox Manager application. Select the VM that is being booted by Vagrant. This can help get the booting process unstuck.
• For more tips and troubleshooting, see the fhooe-webdev Wiki.