Table of Contents:
- What is Vermin
- Install Vermin
- Usage
- Create new VM
- List VMs
- Start VM
- SSH into VM
- Stop VM
- Remove VM
- Transfer Files
- Port Forward
- Commit VM (Create your own images)
- And more
- Contributors
- Why not Vagrant
- TODO
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:
- Install CockroachDB cluster in a Virtual Machine
- Install Redis inside Ubuntu VM
- Install Kubernetes cluster in Virtual Machines the easy way
- Install Desktop environment on Ubuntu Server
Also, you can check Why not Vagrant section.
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'))
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:
- Download the binary matching your OS from releases unzip it and preferably put it in your PATH
- create the following directory structure in your home dir:
$HOME/.vermin
├── images
└── vms
- Download vermin private key into
$HOME/.vermin/vermin_rsa
- On windows, you need to add
C:\Program Files\Oracle\VirtualBox
into you PATH.
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
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.
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).
$ 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
$ vermin start vm_01
$ vermin ssh vm_03
$ vermin stop vm_03
Will stop and remove listed VMs
$ vermin rm vm_03
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
forward ports from VM to local host (all ports from 8080 to 8090):
$ vermin port vm_01 8080-8090
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
- Vagrant uses a
Vagrantfile
which I think is most suited to be source-controlled insidegit
, 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.
Special thanks to Ahmed Samir for contributing the logo.
See TODO.md