Skip to content

mhewedy/vermin

Repository files navigation

Build Status Go Report Card License

logo

The smart virtual machines manager (star the project if you find it useful)

Table of Contents:


What is Vermin

Vermin is a smart, simple and powerful command line tool for Linux, Windows and macOS. It's designed for developers who want a fresh VM environment with a single command. It uses VirtualBox to run the VM. Vermin will fetch images on your behalf.

Vermin can be used when you need an easy way to obtain a Linux environment up and running in minutes. For example:

  • If you want to have an environment to try .NET Core and you don't want to mess with your local own WSL installation.
  • If you want to try to install a Kafka cluster, and you need something more than just a docker container.

Vermin in Action:

Also, you can check Why not Vagrant section.

Install Vermin

Vermin uses VirtualBox as the underlying hypervisor to create and run Virtual Machines. So you need to download and install it first.

To install/update on macos and linux run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mhewedy/vermin/master/install.sh)"

To install/update on windows (PowerShell) run:

# Should run as Adminstarator
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/mhewedy/vermin/master/install.ps1'))

More installation options:

Manual installation:

It is recommended to use the automatic method to install vermin, However If you prefer to do manual installation then you need to follow these steps:

  1. Download the binary matching your OS from releases unzip it and preferably put it in your PATH
  2. create the following directory structure in your home dir:
$HOME/.vermin
         ├── images
         └── vms
  1. Download vermin private key into $HOME/.vermin/vermin_rsa
  2. On windows, you need to add C:\Program Files\Oracle\VirtualBox into you PATH.

Build from Source:

Download the latest released source code archive file from releases then unzip:

go build

You can build using golang docker image:

# replace window by linux or darwin depending on your OS
docker run -it -v $(pwd):/go -e GOPATH='' -e GOOS='windows' golang:latest go build

Usage:

Create, control and connect to VirtualBox VM instances

Usage:
  vermin [command]

Examples:

You can use vermin by creating a VM from an image.

To list all images available:
$ vermin images

Then you can create a vm using:
$ vermin create <image>


Available Commands:
  commit      Commit a VM into a new Image
  completion  Generates shell completion scripts
  cp          Copy files/folders between a VM and the local filesystem or between two VMs
  create      Create a new VM
  exec        Run a command in a running VM
  gui         open the GUI for the VM
  help        Help about any command
  images      List remote and cached images
  ip          Show IP address for a running VM
  mount       Mount local filesystem inside the VM
  port        Forward port(s) from a VM to host
  ps          List VMs
  restart     Restart one or more VMs
  rm          Remove one or more VM
  ssh         ssh into a running VM
  start       Start one or more stopped VMs
  stop        Stop one or more running VMs
  tag         Add or remove tag to a VM
  update      Update configuration of a VM

Flags:
  -h, --help      help for vermin
  -v, --version   version for vermin

Use "vermin [command] --help" for more information about a command.

Create new VM

Use the following command to create a VM

$ vermin create <image name>
# example
$ vermin create ubuntu/focal

Or in case you want to create and provision the VM:

$ vermin create <image name> /path/to/provison.sh 
# example
$ vermin create ubuntu/focal ~/sample.sh --cpus 1 --mem 512

Alternatively, you can provision the VM using an ansible playbook (hosts should set to all):

$ vermin create <image name> -t ansible /path/to/playbook.yaml 
# example
$ vermin create ubuntu/focal -t ansible ~/install-nginx.yaml

See sample provision scripts for sample shell scripts and ansible playbooks.

To get list of all available images use:

$ vermin images
IMAGE NAME               CACHED              DISK
centos/8                 true                0.8GB
ubuntu/focal             true                1.1GB
alpine/3.11

The cached flag means, the image has been already downloaded and cached before.

To get the most updated image list (along with images locations) use the -p flag vermin images -p. this will not affect cached images. it will only get the most updated image list (image names along with thier remote locations).

List VMs

$ vermin ps
VM NAME        IMAGE                      CPUS      MEM       DISK         TAGS
vm_01          alpine/3.11                1         1024      0.8GB
vm_02          ubuntu/focal               1         1024      2.6GB
vm_03          centos/8                   1         1024      2.0GB

Start VM

$ vermin start vm_01

SSH into VM

$ vermin ssh vm_03

Stop VM

$ vermin stop vm_03

Remove VM

Will stop and remove listed VMs

$ vermin rm vm_03

Transfer Files:

You can transfer files between host machine and VM.

To copy a remote file on a VM to you local host in the current path:

$ vermin cp vm_01:/path/to/file/on/vm .

To copy a local file from your host filesystem to the VM's home directory:

$ vermin cp /path/to/file/on/host vm_01:~

Copy file.txt from vm_01 home dir to the vm_02 /tmp dir

$ vermin cp vm_01:~/file.txt vm_02:/tmp

Port Forward:

forward ports from VM to local host (all ports from 8080 to 8090):

$ vermin port vm_01 8080-8090

Commit VM:

You can commit a stopped VM into an image, so later you can create VMs from that image:

$ vermin commit vm_01 elk/elastic

Then you can create as many VMs as you want from the committed image:

$ vermin create elk/elastic

To remove an image at any time later use: (removing an image doesn't remove VMs created from it)

$ vermin image rm elk/elastic

Why not Vagrant:

  • Vagrant uses a Vagrantfile which I think is most suited to be source-controlled inside git , and for some use case it is an overhead to create and maintain such file. In such cases Vermin come to the rescue.
  • Vermin is a single binary file that can be easily installed and upgraded.

Contributors

Special thanks to Ahmed Samir for contributing the logo.

TODO

See TODO.md