Skip to content

Commit

Permalink
Updated README.md
Browse files Browse the repository at this point in the history 
Latest changes and text corrections
  • Loading branch information
@hochleitner
hochleitner committed Mar 1, 2023
1 parent 675244c commit aa8dce5
Showing 1 changed file with 28 additions and 27 deletions.
55 changes: 28 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://www.virtualbox.org/wiki/Downloads> and install. Alternatively, when running Windows, use [Chocolatey](https://chocolatey.org/): `choco install virtualbox`.
2. Download the latest version of Vagrant from <https://www.vagrantup.com/downloads.html> and install. With Chocolatey on Windows run `choco install vagrant`.
1. Download the latest version of VirtualBox from <https://www.virtualbox.org/wiki/Downloads> and install it. Alternatively, when running Windows, use [Chocolatey](https://chocolatey.org/): `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
## 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 <path-to>/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 `<path-to>/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 `<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 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` -> <https://172.16.7.7/code/my_example_project/index.php>
- `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 `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:

- <https://172.16.7.7/code/phpinfo.php>
- <https://172.16.7.7/webapp/phpinfo.php>
- <https://172.167.7.7/phpmyadmin>

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).

0 comments on commit aa8dce5

Please sign in to comment.