Export/Import existing laravel homestead machine

August 20th 2017

When you are developing Laravel application, its always a good idea to use Homestead. This will make it easy to focus on your development rather than spending time in preparing the development environment & dependencies. This article is not a tutorial on how to use Homestead, instead it focusses on exporting and importing an existing Homestead box into another machine. So I assume that you are already familiar in working with Homestead.

`Laravel Homestead` is an official, pre-packaged `Vagrant` box that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine. No more worrying about messing up your operating system! Vagrant boxes are completely disposable. If something goes wrong, you can destroy and re-create the box in minutes!

Now you are already good with running Homestead box and need to export this (probably for a new colleague that joined your team or to use in your home system?). I will go through various steps involved in exporting a Homestead machine. First step is to make sure you are in the Homestead directory.

[email protected]:~$ cd Homestead

Now package the existing box by running the following command.

[email protected]:~/Homestead$ vagrant package --output mynew.box

This will create a new file mynew.box in the Homestead directory. Depending on the size of the machine and the system configuration this could take a few minutes to generate the file.

Now create a new file metadata.json (in the same ‘Homestead’ directory) and place the following content into it.

The above file tells vagrant that the name of the box is laravel/homestead and while importing the box in another machine, homestead will use this local machine than downloading an entire new machine. More on this will follow. Also note the version parameter. The value of the version can be obtained by running the following command

[email protected]:~/Homestead$ vagrant box list
laravel/homestead      (virtualbox, 3.0.0)
puphpet/ubuntu1404-x64 (virtualbox, 20161102)

Notice the number 3.0.0 in the first line of the output. This should be the value of the version parameter in the above metadata.json file.

Now you have successfully exported an existing Homestead machine, it is time to import the box into another machine.

Make sure you have installed Vagrant in the target machine.

You can use the following command to install Homestead in your target machine if not installed already.

[email protected]:~$ git clone https://github.com/laravel/homestead.git Homestead

Change directory to Homestead.

[email protected]:~$ cd Homestead

Checkout to the latest version. At the time of the writing, v6.0.1 is the latest version.

[email protected]:~/Homestead$ git checkout v6.0.1

Run the Homestead script to initialise.

[email protected]:~/Homestead$ bash init.sh

`NOTE:` In windows machine you may need to run `init.bat` by double clicking that file, in order to initialize `Homestead`.

That’s it. Now copy the files mynew.box, Homestead.yaml and metadata.json (from the Homestead directory of the parent machine) to the Homestead directory of target machine to begin the import.

Do the necessary changes to the Homestead.yaml file if needed. A sample Homestead.yaml file can be found below.

Now finally to import the box, run the following command in the Homestead directory of the target machine.

[email protected]:~/Homestead$ vagrant box add metadata.json

Note that we are adding `metadata.josn` and not `mynew.box` in the above command. This is important, else `Homestead` will try to download the latest version from internet than using the local copy. It may also set the box `metadata` version to `0` and cause more troubles in the future. So using `metadata.json` for import could prevent all this together!

Now it’s time to run the imported Homestead machine. Happy Coding!

[email protected]:~/Homestead$ vagrant up

If everything goes fine and you see no errors, then congrats! You have successfully imported Homestead machine to a new system. You may need to change some values like nginx configuration in the new machine manually as this will be overwritten at the time of import.

Also note that while most of the configurations in the exported machine will remain same, some configurations like changes done to `nginx` files will be overwritten in the imported machine.

The whole tutorial is focused on running Homestead in Linux. However the same also should work in any Mac system. You could also use this tutorial concept to Export/Import Homestead machine in Windows system with little adjustments. Let me know what you have to say through the comment section below.

Make sure you have installed Vagrant in the target machine.

NOTE: In windows machine you may need to run init.bat by double clicking that file, in order to initialize Homestead.

Also note that while most of the configurations in the exported machine will remain same, some configurations like changes done to nginx files will be overwritten in the imported machine.

Your comments

`NOTE:` In windows machine you may need to run `init.bat` by double clicking that file, in order to initialize `Homestead`.

Also note that while most of the configurations in the exported machine will remain same, some configurations like changes done to `nginx` files will be overwritten in the imported machine.