Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Team Workflows

Packaging and Hosting Private Boxes

Turn a configured machine into a reusable box with vagrant package, prepare a clean base, host it privately with a metadata JSON file, and version it for your team.

Public boxes are great starting points, but a team often wants its own: Ubuntu with the company's CA certificate, Java, a database and a warmed package cache already installed. Provisioning all that on every vagrant up takes minutes. A custom box moves the slow, stable part into a prebuilt image, so new machines start in seconds and every teammate gets identical software.

What a box is

A box is just an archive (usually .box, a tar or gzip file) containing:

  • metadata.json: the provider name (for example {"provider": "virtualbox"});
  • the disk image and machine description for that provider;
  • optionally a Vagrantfile with defaults that apply to every machine made from the box.

You can inspect one with tar tf my.box.

From machine to shared box

Prepare Install and clean up
Package vagrant package
Host Upload and publish
Use config.vm.box_url

Rebuild the box whenever the base changes.

1 / 2

Preparing a clean base

Start from a normal machine, set it up, then make it fit for sharing. These steps matter more than the packaging command itself.

TEXT
$ vagrant up
$ vagrant ssh
$ sudo apt-get update && sudo apt-get install -y openjdk-17-jdk git ca-certificates
$ sudo apt-get clean
$ sudo rm -rf /var/lib/apt/lists/* /tmp/* ~/.bash_history
$ sudo dd if=/dev/zero of=/EMPTY bs=1M || true; sudo rm -f /EMPTY   # zero free space so it compresses
$ history -c && exit

Checklist for a good base box:

  1. Keep the default vagrant user and its insecure public key, so vagrant ssh keeps working (Vagrant swaps in a private key on first boot).
  2. Passwordless sudo for that user.
  3. SSH server running on boot.
  4. Remove caches, logs, shell history and machine-specific data (SSH host keys can be regenerated on first boot).
  5. Never leave real credentials in it.

Also zeroing free space, as in the dd line, lets the final image compress to a smaller archive.

Packaging

TEXT
$ vagrant package --output team-java17.box
==> default: Attempting graceful shutdown of VM...
==> default: Clearing any previously set forwarded ports...
==> default: Exporting VM...
==> default: Compressing package to: /home/me/vm/team-java17.box

$ ls -lh team-java17.box
-rw-r--r-- 1 me me 812M team-java17.box

For a machine in a multi-machine project, name it: vagrant package web --output web.box. To add a default Vagrantfile inside, pass --vagrantfile defaults.rb.

Test the box locally before you share it:

TEXT
$ vagrant box add team/java17 ./team-java17.box
$ mkdir /tmp/box-test && cd /tmp/box-test
$ vagrant init team/java17 && vagrant up

Only publish after a clean machine boots from it and vagrant ssh works.

Hosting a box privately

You have several options.

  • Vagrant Cloud (the public registry) accepts private boxes on paid plans.
  • A web server or object store such as an S3 bucket or an internal file server. Any HTTPS URL that serves the file works.
  • A shared network path, handy for small teams: config.vm.box_url = "file:///mnt/share/team-java17.box".

The simplest use is to point a Vagrantfile at a URL:

Ruby
config.vm.box = "team/java17"
config.vm.box_url = "https://boxes.example.com/team-java17.box"

Vagrant downloads it once and stores it in ~/.vagrant.d/boxes.

Versioning with a metadata file

To give your own host real version handling (so vagrant box outdated and box_version work), serve a small JSON document and point box_url at it.

JSON
{
  "name": "team/java17",
  "description": "Ubuntu 22.04 with Java 17 and team CA",
  "versions": [
    {
      "version": "1.1.0",
      "providers": [
        {
          "name": "virtualbox",
          "url": "https://boxes.example.com/team-java17-1.1.0.box",
          "checksum_type": "sha256",
          "checksum": "9c1f5a..."
        }
      ]
    },
    {
      "version": "1.0.0",
      "providers": [
        {
          "name": "virtualbox",
          "url": "https://boxes.example.com/team-java17-1.0.0.box",
          "checksum_type": "sha256",
          "checksum": "41ad07..."
        }
      ]
    }
  ]
}
Ruby
config.vm.box = "team/java17"
config.vm.box_url = "https://boxes.example.com/team-java17.json"
config.vm.box_version = "~> 1.0"

Generate checksums with sha256sum team-java17-1.1.0.box. Vagrant verifies them on download, which protects against corrupted or tampered files. Combine this with version constraints to roll out upgrades on your terms.

Alternatives to a box

A custom box is a good fit for slow installs. For small differences, a provisioning script is easier to review and change. A useful rule: if provisioning takes under two minutes and changes weekly, keep it in the Vagrantfile. If it takes ten minutes and changes quarterly, build a box. Tools such as Packer can build boxes from a script in a repeatable way, so you do not hand-craft a machine each time.

A stand-in: generate the metadata JSON

You can produce the version file with a few lines of Ruby. This runs on the site because it only needs the standard library; the checksums here are computed from fake file contents.

Ruby Build box metadata

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

In practice a release script computes the checksum from the real .box file with Digest::SHA256.file(path).hexdigest and uploads both.

Common mistakes

  • Leaving secrets or history in the machine before packaging.
  • Packaging a box with a changed SSH key setup, which breaks vagrant ssh for users.
  • Overwriting a published version. Always publish a new version number.
  • A large box and no checksum. A broken download wastes everyone's time; always set the checksum.
  • Forgetting that Guest Additions need to match the user's VirtualBox version, or use vagrant-vbguest.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command turns a running machine into a box file?

    vagrant package exports the machine to a .box archive.
  2. 2. Why serve a metadata JSON file with versions?

    The metadata lists versions, providers, URLs and checksums so Vagrant can resolve and verify them.
  3. 3. What should you do before packaging a machine?

    A shared box must not carry secrets, and it must keep the standard access path so vagrant ssh works.
  4. 4. When is a custom box better than a provisioning script?

    Move slow, stable setup into a box; keep fast-changing setup in provisioners.

Summary

  • A box is an archive with provider metadata and a disk image; vagrant package creates it.
  • Clean and prepare the base carefully: no secrets, working SSH, compressed free space.
  • Host boxes on any HTTPS or file URL; use a metadata JSON with versions and checksums for real version control.
  • Choose boxes for slow, stable setup and provisioners for fast-changing setup.

Next: Debugging and common errors