diff --git a/README.md b/README.md index 0adc396..6ecce50 100644 --- a/README.md +++ b/README.md @@ -2,59 +2,60 @@ 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](https://www.fh-ooe.at/en/hagenberg-campus/). -The Vagrantfile works with our own [fhooe/fhooe-webdev box](https://app.vagrantup.com/fhooe/boxes/fhooe-webdev), which is based on Ubuntu 21.10 and includes Apache2, PHP 8.1, MariaDB 10.7, as well as additional tools and scripts. +The Vagrantfile works with our own [fhooe/fhooe-webdev box](https://app.vagrantup.com/fhooe/boxes/fhooe-webdev), 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](https://www.vagrantup.com/intro/) first. +Not familiar with Vagrant or not sure why to use it? Have a look at the [Introduction](https://www.vagrantup.com/intro/) first. -## Installation of software and prerequisites +## Installation of Software and Prerequisites To use this environment, you will need [VirtualBox](https://www.virtualbox.org/) and [Vagrant](https://www.vagrantup.com/). 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. -* [Mac OS X] Make sure, VirtualBox has the necessary permissions. Go to "System Settings -> Security -> Allow Virtual Box". +* 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 and install. Alternatively, when running Windows, use [Chocolatey](https://chocolatey.org/): `choco install virtualbox`. -2. Download the latest version of Vagrant from and install. With Chocolatey on Windows run `choco install vagrant`. +1. Download the latest version of VirtualBox from and install it. Alternatively, when running Windows, use [Chocolatey](https://chocolatey.org/): `choco install virtualbox`. +2. Download the latest version of Vagrant from 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 +## How to Use the Vagrantfile 1. Download or clone the [fhooe-webdev](https://github.com/Digital-Media/fhooe-webdev) repository to a location of your choice on your computer. If you don't want the whole repository, downloading the [Vagrantfile](https://github.com/Digital-Media/fhooe-webdev/blob/master/Vagrantfile) will suffice. -2. Open PowerShell, a command prompt or the terminal. +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 /fhooe-webdev`. -4. Run `vagrant up`. This will download the [fhooe/fhooe-webdev box](https://app.vagrantup.com/fhooe/boxes/fhooe-webdev) (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 sucessfully, 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`. +4. Run `vagrant up`. This will download the [fhooe/fhooe-webdev box](https://app.vagrantup.com/fhooe/boxes/fhooe-webdev) (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 +## How to Use the Image for Web Development -Once the image has successfully booted you will notice that a folder called `code` inside of your `/fhooe-webdev` directory has been created. This directory is mapped to `/var/www/html/code` 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. +Once the image has successfully been booted, you will notice that a folder called `webapp` inside your `/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 therefore its web server - under this address. +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 `code` folder on your host machine. They will be instantly available through the Vagrant image's web server at 172.16.7.7. E.g.: +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.: -- `code/my_example_project/index.php` -> +- `webapp/my_example_project/index.php` -> -There's a file called `phpinfo.php` in the `code` directory that allows you to quickly check the configuration of this image. Also [phpMyAdmin](https://www.phpmyadmin.net/) is already installed and configured. These are available here: +There's a file called `phpinfo.php` in the `webapp` directory that allows you to check the configuration of this image quickly. Also, [phpMyAdmin](https://www.phpmyadmin.net/) is already installed and configured. These are available here: -- +- - -The default configuration uses HTTPS and mimics a production webserver without displaying any PHP errors. To work without HTTPS (thus avoiding the certificate warning), open your files with HTTP on port 81. E.g.: +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/code/ for the code directory. +- 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 `code` directory is affected. +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 +## 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. +- 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](https://github.com/Digital-Media/fhooe-webdev/wiki).