Developer VM Documentation Issue #321

New Issue

2026-06-29T08:37:46Z

rob commented

2026-06-29 08:37:46 +00:00

This issue serves as reference documentation for setting up a development VM, using the mid-2020 dev-vm setup.

This is mostly aimed at @rob - and assumes he'll be running on a mac. Others can follow along, and adapt these instructions to themselves, no matter what os they're using.

Prerequisites

A computer, running MacOS, Linux, or Windows. This document focuses on MacOS, but should work for users with Linux or Windows too.
An up-to-date install of VirtualBox
An up-to-date install of vagrant
An SSH keypair, with the public key added to your gitlab account. (Test from your local terminal with: ssh -T git@git.estack.com -- it should reply with Welcome to GitLab, @rob!)

Video

There's a video to help you get through getting your mac set up to run a dev-vm. It pretty closely follows the instructions below. View it here: https://www.loom.com/share/0bf65e56ae394bc48f53468859d6c5b1

Getting the source code

Clone this repository to your local machine. I suggest making a "Code" directory in your home directory, and checking the project out there. In a terminal, you could do:

$ mkdir -p ~/estack
$ cd ~/estack
$ git clone git@git.estack.com:tim/pms3.git

Any time you want to do something in the terminal, you can open a new terminal and type cd ~/estack/pms3 to navigate to the eStack code directory.

Installing VirtualBox and Vagrant

You can follow the installation instructions at the respective websites for any OS. If you're running MacOS or Linux, you might consider using a system package manager like apt or brew

Homebrew

If you're on a mac, you can use homebrew, and a handy script included in the eStack code:

$ cd ~/estack/pms3
$ ./mac-os-developer-setup.sh

Hit enter when prompted. Enter your MacOS password as needed.

Verifying VirtualBox and vagrant versions from the command-line

In a terminal, you can run the following commands. They should report versions >= 6.1.x for VirtualBox and >= 2.x for vagrant:

$ VBoxManage -version

$ vagrant -v

VPN Configuration

Our VMs can connect to a private network, which is useful for troubleshooting and testing. Each VM gets its own configuration, which contains some secrets, so you'll need to get your config from @tim. The configuration file is called wg.conf, and should be placed in the dev-scripts (beside the wireguard.sh script) in your work dir.

You can copy it there using the Finder, or use a terminal (assuming here you've downloaded it to your Downloads folder):

$ cp ~/Downloads/wg.conf ~/estack/pms3/dev-scripts/wg.conf

Boot your VM for the first time

There's another video here: https://www.loom.com/share/b2b5268a627848de89cdec4bf87eb6fa

This is easy. From inside your pms3 directory:

$ cd ~/estack/pms3
$ vagrant up

The first time you run this, it will download the VM image, which is approximately 1GB, and may take some time.

Once you're returned to the prompt, you should be able to SSH into the box by running vagrant ssh:

Install dependencies

While SSH'd into the VM, run composer install from inside the /estack dir:

you@host:pms3$ vagrant ssh
vagrant@vm:~$ cd /estack
vagrant@vm:/estack$ composer install

If you're prompted about the authenticity of git.estack.com, enter 'yes' followed by hitting enter, so the process can continue.

After installing a bunch of packages, it should print a line that says Generating autoload files (in green), and return you to the prompt. You can ignore any warnings that might be printed during the install process.

Smoke Test

At this point, you should have a functioning development environment. You won't have any eStack instances, but you should be able to see a login page at: https://cb.vm.estack.com/

You'll have to ignore an SSL warning in your browser, but once you do, you should see the familiar login screen.

NOTE: Trying to log in will fail. cb is a special name in the system, but there's no actual database behind this instance.

Create a real customer instance

Creating a real customer instance is pretty straightforward.

First, make sure you're logged into the VM: vagrant ssh

Then change to the /estack directory: cd /estack

Then run the command to create a new instance: bin/pms3 customer create-new <custId> (where <custId> is the customer-identifier (think 'cb') for the new instance. It looks like this:

This issue serves as reference documentation for setting up a development VM, using the mid-2020 dev-vm setup. This is mostly aimed at @rob - and assumes he'll be running on a mac. Others can follow along, and adapt these instructions to themselves, no matter what os they're using. # Prerequisites * A computer, running MacOS, Linux, or Windows. This document focuses on MacOS, but should work for users with Linux or Windows too. * An up-to-date install of [VirtualBox] * An up-to-date install of [vagrant] * An SSH keypair, with the public key added to your gitlab account. (Test from your local terminal with: `ssh -T git@git.estack.com` -- it should reply with `Welcome to GitLab, @rob!`) ## Video There's a video to help you get through getting your mac set up to run a dev-vm. It pretty closely follows the instructions below. View it here: https://www.loom.com/share/0bf65e56ae394bc48f53468859d6c5b1 ## Getting the source code Clone this repository to your local machine. I suggest making a "Code" directory in your home directory, and checking the project out there. In a terminal, you could do: ```bash $ mkdir -p ~/estack $ cd ~/estack $ git clone git@git.estack.com:tim/pms3.git ``` Any time you want to do something in the terminal, you can open a new terminal and type `cd ~/estack/pms3` to navigate to the eStack code directory. ## Installing VirtualBox and Vagrant You can follow the installation instructions at the respective websites for any OS. If you're running MacOS or Linux, you might consider using a system package manager like `apt` or `brew` ### Homebrew If you're on a mac, you can use homebrew, and a handy script included in the eStack code: ``` $ cd ~/estack/pms3 $ ./mac-os-developer-setup.sh ``` Hit enter when prompted. Enter your MacOS password as needed. ## Verifying VirtualBox and vagrant versions from the command-line In a terminal, you can run the following commands. They should report versions >= 6.1.x for VirtualBox and >= 2.x for vagrant: ```sh $ VBoxManage -version ``` ```sh $ vagrant -v ``` # VPN Configuration Our VMs can connect to a private network, which is useful for troubleshooting and testing. Each VM gets its own configuration, which contains some secrets, so you'll need to get your config from @tim. The configuration file is called `wg.conf`, and should be placed in the `dev-scripts` (beside the `wireguard.sh` script) in your work dir. You can copy it there using the Finder, or use a terminal (assuming here you've downloaded it to your Downloads folder): ```sh $ cp ~/Downloads/wg.conf ~/estack/pms3/dev-scripts/wg.conf ``` # Boot your VM for the first time There's another video here: https://www.loom.com/share/b2b5268a627848de89cdec4bf87eb6fa This is easy. From inside your `pms3` directory: ```bash $ cd ~/estack/pms3 $ vagrant up ``` The first time you run this, it will download the VM image, which is approximately 1GB, and may take some time. Once you're returned to the prompt, you should be able to SSH into the box by running `vagrant ssh`: ![image](/uploads/739a57c1af7fc848dde7da97736f1bc0/image.png) # Install dependencies While SSH'd into the VM, run `composer install` from inside the /estack dir: ```sh you@host:pms3$ vagrant ssh vagrant@vm:~$ cd /estack vagrant@vm:/estack$ composer install ``` If you're prompted about the authenticity of `git.estack.com`, enter 'yes' followed by hitting enter, so the process can continue. After installing a bunch of packages, it should print a line that says `Generating autoload files` (in green), and return you to the prompt. You can ignore any warnings that might be printed during the install process. # Smoke Test At this point, you should have a functioning development environment. You won't have any eStack instances, but you should be able to see a login page at: https://cb.vm.estack.com/ You'll have to ignore an SSL warning in your browser, but once you do, you should see the familiar login screen. **NOTE**: Trying to log in will fail. `cb` is a special name in the system, but there's no actual database behind this instance. # Create a real customer instance Creating a real customer instance is pretty straightforward. First, make sure you're logged into the VM: `vagrant ssh` Then change to the /estack directory: `cd /estack` Then run the command to create a new instance: `bin/pms3 customer create-new <custId>` (where `<custId>` is the customer-identifier (think 'cb') for the new instance. It looks like this: [VirtualBox]: https://www.virtualbox.org/wiki/Downloads [vagrant]: https://www.vagrantup.com/downloads [homebrew]: https://brew.sh/

Sign in to join this conversation.

No Label

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rob/pms3#321