Virtual Machine (VM)

The Frontastic VM provides you with a development setup that should work out of the box and give you a wide range of development tools once it is setup. For this reason we do not ask you install all required software on your machine, but provide an automation to setup a Virtual Machine which contains everything as close as possible to the other Frontastic environments (Staging & Production).

We are using Vagrant to orchestrate the how Virtual Machines are setup. By default we use VirtualBox as the machine provider but it is also possible to use Docker.

It may be helpful to read up a little about Vagrant, VirtualBox and Docker on their websites to get a glimpse on these technologies especially if you run into trouble. Their documentation and sources like Stack-Overflow are really good. For the pure purpose of working with Frontastic we have summarised the most important information about our VM stack below:

Pre-requisites

For basic pre-requisites please see README.md in the root directory of your checkout.

First Time Boot

To initially start the VM type

host:frontastic $ vagrant up --provision

on the shell while you are inside of the root directory of your checkout. Vagrant will now run for quite some time performing the following steps:

  1. Download the base-box which contains the operating system and some basic software (for VirtualBox this is a slim Ubuntu image)
  2. Setup SSH connection to the machine and mount the required folders for the setup process
  3. Start the provisioning which is then executed by Ansible inside the Virtual Machine

Step 3 is the most extensive one and can take a severe amount of time. If you want to read more about what is done during this step, please refer to TODO: Provisioning.

After the provisioning has completed successfully, your machine is ready to go and you should be able to access the developer landing page at [http://frontastic.io.local].

Working on the Shell

While your source code should be synchronised to the VM automatically to be executed (see README.md!) there are many reasons why you would want to access the shell of the VM (e.g. clearing caches, restarting deamons, watching logs ... you find more in [commands.md]). You can do so by executing

host:frontastic $ vagrant ssh

on the shell in the root of your checkout. This brings you into the machine by SSH and you find yourself as the user vagrant in the mounted checkout of your source code in /var/www/frontastic.

All files in the project checkout should be owned by the vagrant user so you can access them in this state. If you require additional permissions to access system components (e.g. the syslog) you can simply use sudo to acquire root permissions without any password.

Exiting this shell (using the exit command or <Ctrl>+<d>) in the VM just brings you back to your host system as with any other SSH connection.

There might be reasons why you would want to access the VM via SSH without using the vagrant ssh command (e.g. because you prefer a GUI client or your IDE supports working with VMs through SSH). You can see the required setting on your shell using

host:frontastic $ vagrant ssh-config

Halt and Restart

Once you are done with your day or if you need to switch to another project, you want to shutdown the Frontastic VM to safe resources. This can be done using

host:frontastic $ vagrant halt

When this command has finished, the VM has shutdown as if you would powerdown the computer that it contains.

Vagrant and Suspend/Hibernate/Sleep

Vagrant machines might experience trouble if you leave them running while you put your host machine into a sleep mode. We therefore recommend to shut down the VM properly before suspending your host.

If you want to resume work you can simply do

host:frontastic $ vagrant up

Note that the --provision flag was left out in this case. If you perform the up command without this flag, the machine will just be booted and provisioning will not be started again. This is fine when you halt/boot multiple times a day, but we recommend using vagrant up --provision at least once a day to ensure new required software is installed and dependencies are pulled in correctly.

Destroying

It might happen that your VM is damaged or that you stop working on the project and therefore want to get rid of it. Using

host:frontastic $ vagrant destroy

and confirming that you really want to destroy the VM will achieve this.

Please note that if you want to achieve an entirely clean state you need to delete your checkout and perform a new clone of the repository. This is due to the fact that provisioning generates files in your checkout (dependencies in node_modules and vendor directories but also environment files) which are not removed during vagrant destroy.

Further Reading

If you want to learn more about which tasks you can perform inside the Frontastic VM for development purposes please refer to [commands.md]. It might also be a good idea to learn more about the TODO: System structure.