A Local Development VM with Vagrant
A local web project can depend on more than its source files. The Linux distribution, PHP packages, and system configuration can all affect how it runs. Vagrant gives you a way to describe a development VM in a project file and bring it up again when you need it.
1. Start with a box that matches your machine
Install Vagrant and a supported virtualization provider. This example uses VirtualBox. In the Vagrant box catalog, choose a Linux box that supports VirtualBox and your host’s CPU architecture. The example uses bento/ubuntu-24.04. Check the box’s provider and architecture before using it, especially on an ARM host.
Start in a new directory so the lab has its own Vagrantfile.
mkdir vagrant-web-lab
cd vagrant-web-lab
vagrant init bento/ubuntu-24.04
vagrant up --provider=virtualbox
vagrant status
The first start may need to download the base box. If Vagrant cannot find a compatible box, check the provider and architecture on its catalog page. If VirtualBox itself fails to start the VM, check its error message before changing the project configuration.
2. Check the guest and the shared directory
Run these two commands on the host:
printf 'Hello from the host\n' > hello.txt
vagrant ssh
Then run these inside the VM:
cat /etc/os-release
cat /vagrant/hello.txt
exit
The first command identifies the guest OS. The second should show the line you wrote on the host. Vagrant normally syncs the project directory to /vagrant. If that file is missing, check the synced-folder messages from vagrant up and any custom folder settings in your Vagrantfile.
3. Decide which parts should survive a rebuild
Run vagrant halt when you want to stop the VM and keep its disk. Use vagrant up to start it again. In a disposable lab, vagrant destroy removes the guest and its local state, so move any guest-only files you want to keep before using it.
For a real project, commit the Vagrantfile and any provisioning scripts. Keep the application source in the project directory. If the VM needs a web server or specific extensions, put those setup steps in provisioning so you can see exactly what another developer would need to reproduce.