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).
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:
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:
- Download the base-box which contains the operating system and some basic software (for VirtualBox this is a slim Ubuntu image)
- Setup SSH connection to the machine and mount the required folders for the setup process
- 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
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
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
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
vendor directories but also
environment files) which are
not removed during
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.