Getting Started

Bootstrapping a new machine (or using mstrap for the first time)

Prerequisites

  • If you use nodenv, nvm, rbenv, rvm, chruby, pyenv, or other language runtime version managers for Ruby, Python, Node.js, or PHP: uninstall them first. They will likely conflict with asdf-vm or mise.
  • GitHub users: If you’re pulling dotfiles, a personal Brewfile, or other private repos:
    1. Ensure you’ve generated an SSH key for your machine and attached it to your GitHub account

Bootstrapping

  1. In a Terminal window, run mstrap to run the whole suite. If you’re not passing configuration options or a remote configuration file, you will be prompted for various details.
  2. When you see mstrap has completed successfully!, it’s done! Yay! Now we have a bootstrapped system!
  3. Restart your terminal
  4. Verify that echo $MSTRAP prints true.
    • If it does, you’re done!
    • If it does not, ensure that ~/.mstrap/env.sh is getting loaded into the environment by your shell configuration, restart your terminal, and repeat this step.

Configuring Projects

After the above section, you now have a bootstrapped system. However, bootstrapped with what? It is a fairly bare machine still. mstrap has setup Homebrew, installed system updates, set some sensible system defaults, and maybe cloned and setup our dotfiles if we provided it a GitHub username and have a dotfiles repo with a script/setup.

But what’s next? Where are my projects? How do I set those up? If you’re bootstrapping a new machine or have never used mstrap before, you’re not yet taking care of the tedious work of cloning all your projects, installing the various versions of language runtimes, installing dependencies, and other tasks.

For this, we need to provide a little configuration. The default profile is how we can specify where our projects are, how they should be configured, and any global packages we need for various language runtimes.

The default profile is stored at ~/.config/mstrap/profile.hcl, so we we’ll put this there:

runtime "ruby" {
  package "brakeman" {}
  package "bundle-audit" {}
}

runtime "node" {
  package "pnpm" {}
  package "release-it" {}
}

runtime "rust" {
  package "ripgrep" {
    version = "14.1.0"
  }
}

project "infra-config" {
  name = "Infrastructure Config"
  repo = "ssh://git@github.com:maxfierke/infra-config.git"
}

project "resumis" {
  name = "Resumis"
  port = 5000
  repo = "ssh://git@github.com:maxfierke/resumis.git"
}

Here I’ve defined a couple projects. One is an infrastructure project. It doesn’t require much bootstrapping, so it doesn’t require much of any configuration as it really just needs to be cloned. Another project, Resumis, is a Ruby on Rails web application, so I specify the port it runs on as 5000. mstrap will detect it as a Ruby project (due to it having a Gemfile), a Node project (due to it having a package.json), and a web project (since I configured a port), so that it gets setup in nginx correctly and I’ll be able to reach it at resumis.localhost.

For more information about setting up a profile, check out the Profiles reference page.

For more information about making a project “mstrap-ready” check out the Projects reference page.

Bootstrapping from a remote configuration

mstrap also supports being bootstrapped from a remote configuration. Running mstrap -c https://url/to/config.hcl will pull the config in and use it as the configuration.

The config will be written to disk in the default location when the init step runs, e.g. as part of running mstrap -c https://url/to/config.hcl with no step specified, or mstrap -c https://url/to/config.hcl init.

Security Note: Do not bootstrap with any remote configurations you do not trust. Remote configurations have the potential to execute programs via projects bootstrapped or packages installed through managed profiles.

For more information on config.hcl, see the Configuration page.

Maintaining a bootstrapped machine

Once mstrap has run on a machine, keeping it up-to-date is just a matter of running mstrap every now and then.

If you’ve made some changes to a managed profile, run mstrap update-profiles to fetch the latest version. Next, you can run mstrap again to apply those changes.

You can also run steps individually. For example, to make sure your Docker services are up-to-date (or to recreate the containers), you can run mstrap services. Run mstrap steps to see all the steps that are available. mstrap --help also provides more information about what each step does.

Reference: Usage →