This lesson will establish the local workspace, explain how to launch the box, how to know when it is ready for interaction, how to shut it down, and how to keep it up-to-date.
Create local workspace
Make a fresh directory, change into it and create the Vagrantfile.
For the stable and current FOLIO flower release use this:
mkdir folio-release cd folio-release cat > Vagrantfile << 'EOF' Vagrant.configure("2") do |config| config.vm.box = "folio/release" config.vm.provider "virtualbox" do |vb| vb.memory = 24576 vb.cpus = 2 end end EOF
As a developer you may use the daily snapshot instead. It contains the head of development but may break sometimes:
mkdir folio-snapshot cd folio-snapshot cat > Vagrantfile << 'EOF' Vagrant.configure("2") do |config| config.vm.box = "folio/snapshot" config.vm.provider "virtualbox" do |vb| vb.memory = 24576 vb.cpus = 2 end end EOF
That setup was a once-off task.
Any file that is placed in this directory on the host system will be shared on the guest at the /vagrant mount point.
Modify the Vagrantfile as needed, for example increasing allowed memory and cpus.
Launch the guest
Launch the VirtualBox guest:
The output will show the VM starting. (If this is the first launch then the box will be downloaded, which will take some time.) When the command prompt is returned, then the system will be ready to inspect.
However wait a while before attempting to interact, because Okapi will still be starting modules, this may take about 5-30 minutes.
Some ports of the guest will be forwarded to the host, so that the FOLIO system can be reached from the outside. Okapi will be listening on localhost port 9130, and the Stripes development server will be on localhost port 3000.
Connect to the guest
In a terminal window on the host, connect to the VirtualBox guest:
Follow the Okapi logfile to determine when the system is ready for interaction:
docker logs okapi -n 100 -f
Try connect to service” messages indicate that Okapi is still starting modules.
When Okapi pauses occasionally and shows bursts of “Timer” tasks, then it should be ready for interaction.
Quick visit to UI
Use the local web browser to login to the user interface at
The default administrative user is
Inspect the Settings page to find the version of Okapi, and the installed modules:
Note: If errors are presented, then you probably did not wait long enough, it takes about 5-30 minutes. Do logout, wait, and then log in again.
Halt and rest
Okay, that is enough fun. Now we are going to get out, and show how to halt and update the box.
Ctrl-C’ to stop following the logfile.
Get out of the VM guest and return to the host. Do ‘
Now put the system to rest with ‘
When ready to recommence, simply do ‘
Update the box
As explained in the background overview section, the FOLIO VMs are regularly rebuilt with the current state of development.
The local system does not need to be updated every day, but when desired then do:
vagrant halt’ and then ‘
vagrant box update’
(followed by ‘
vagrant destroy’ to disable the old default machine).
The Vagrant box can then be launched again with ‘
Destroy when finished
When finished with exploration, do ‘
vagrant destroy’ to reclaim disk space and keep your vagrant tidy.
When ready to use it again, then do ‘
vagrant up’ again.
Of course, if you had done additional configuration to the default system or loaded extra data or other modules, then that would need to be repeated.
For further assistance with Vagrant and management of virtual environments, see the HashiCorp Learn tutorials. For example additional notes about suspend, halt, destroy.
Next lesson: VM system overview