# The shipyard The `shipyard` is a small wrapper around vagrant and libvirt that allows you to manage virtual machines easily. For most commands you only need to provide the hostname. ## Installation First you need to setup you machine. Follow the [istructions to run the`shipyard_setup` script here](../start-here). Now clone this repo,`cd` into `shipyard/`, and launch the command: ```bash ./shipyard ``` Feel free to copy the script to `~/bin` or symlink it so you don't need to enter the directory every time you run the script. ## How it works Shipyard uses `~/.config/ldh_developer/shipyard` as configuration directory. Every folder inside the `shipyard` folder represents a vagrant box, so for a box with hostname `floyd` the `$VAGRANT_HOME` directory is `~/.config/lds_developer/shipyard/floyd`: ```bash ls -l ~/.config/ldh_developer/shipyard/ total 8 drwxr-xr-x 3 nnieto nnieto 4.0K Nov 27 21:46 floyd/ ``` The `floyd` folder contains two files (`Vagrantfile` and `shim.yml`) and the vagrant hidden folder(`.vagrant`). Once `shipyard` creates a box, you can manage it with the libvirt and vagrant tools of your choice. Recommended tools are: - [GNOME Vagrant Indicator](https://github.com/fffilo/gnome-vagrant-indicator) - virt-manager (apt install virt-manager) ## Commands `shipyard` supports these commands: - `status`: report the status of the virtual machines created/managed by `shipyard`. - `create`: create a new VM. You only need to provide the hostname. - `up`: starts a VM. - `halt`: stops a VM. - `destroy`: destroys the VM - `ssh`: opens a ssh session directly to the VM as `vagrant` user. - `playbook`: provisions a VM with an ansible playbook. - `which`: prints the configuration directory path of a VM. - `open`: opens the configuration directory of a VM with the current file manager (nautilus, dolphin, etc.) ### The `status` command Prints a summary of the state of all VM's managed by `shipyard`. Example: ``` $ shipyard status hostname State IP Address nina running 192.168.121.185 pinta shutoff stmaria running 192.168.121.178 Total 3 machine(s) $ ``` ### The `create` command This command creates a new VM. You only need to provide the hostname. But you can specify the ram size and the number of cpus. The following example creates a VM with the hostname `usoland`. The default values for ram size is 512 MB, and 1 CPU. ``` $ shipyard create usoland Bringing machine 'usoland' up with 'libvirt' provider... ==> usoland: Checking if box 'debian/stretch64' is up to date... [...] ==> usoland: -- Memory: 512M [...] ==> usoland: -- Cpus: 1 [...] ``` The following example creates a VM with the hostname `usoland` with 4 cpus and 1GB of ram: ``` $ shipyard create usoland --cpus 4 --ram 1024 Bringing machine 'usoland' up with 'libvirt' provider... [...] ==> usoland: -- Cpus: 4 [...] ==> usoland: -- Memory: 1024M [...] ==> usoland: Pruning invalid NFS exports. Administrator privileges will be required... ==> usoland: Creating shared folders metadata... usoland: Running ansible-playbook... [...] $ ``` **Note**: Vagrant/libvirt need root access to create and modify networks on the machine. Vagrant will try to use sudo and will request your passowrd. ### The `up` and `halt` commands Use these commands to start and shutdown the VM's. As an example, the previous section we created one vm. If we check the status we find that it's running. ``` $ shipyard status hostname State IP Address usoland running 192.168.121.57 Total 1 machine(s) $ ``` Now, let's use the `halt` command. ``` shipyard halt usoland ==> usoland: Halting domain... $ ``` We can see that the VM status is `shutoff`: ``` $ shipyard status hostname State IP Address usoland shutoff Total 1 machine(s) $ ``` We use the `up` command to start the VM again. ``` $ shipyard up usoland Bringing machine 'usoland' up with 'libvirt' provider... ==> usoland: Checking if box 'debian/stretch64' is up to date... ==> usoland: Starting domain. ==> usoland: Waiting for domain to get an IP address... ==> usoland: Waiting for SSH to become available... ==> usoland: Creating shared folders metadata... ==> usoland: Exporting NFS shared folders... ==> usoland: Preparing to edit /etc/exports. Administrator privileges will be required... ==> usoland: Mounting NFS shared folders... ==> usoland: Machine already provisioned. Run `vagrant provision` or use the `--provision` ==> usoland: flag to force provisioning. Provisioners marked to run always will still run. $ ``` Now `status` shows that the vm is running. ``` $ shipyard status hostname State IP Address usoland running 192.168.121.57 Total 1 machine(s) $ ``` ### The `ssh` command The ssh command opens an ssh to the VM. ```bash $ shipyard ssh usoland Linux usoland 4.9.0-8-amd64 #1 SMP Debian 4.9.130-2 (2018-10-27) x86_64 The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. Last login: Fri Nov 30 07:26:45 2018 from 192.168.121.1 vagrant@usoland:~$ logout Connection to 192.168.121.57 closed. $ ``` ### The `which` command The `which` command prints the full path to the `$VAGRANT_HOME` directory of the VM. ``` $ shipyard which usoland /home/nnieto/.config/ldh_developer/shipyard/usoland $ ``` ### The `open` command This command opens a new window of your file manager pointing to the `$VAGRANT_HOME` of the VM. ```bash ./shipyard open --hostname=starone0 [... nautilis shows up ...] ``` ### The `ansible` command This command allows you to run an ansible playbook against one of the VMs. For example: I have two VM's managed by `shipyard`: ``` ./shipyard status hostname State IP Address usoland shutoff going-merry running 192.168.121.89 Total 2 machine(s) ``` Let's install rust on`going-merry`. The playbook looks like this: ```yaml --- - name: Rust Playbook become: yes hosts: all tasks: - name: Install Rust apt: name=rustc update_cache=yes ``` Let's save it as `rust.yml` and run the playbook against `going-merry`: ``` ./shipyard playbook going-merry rust.yaml PLAY [Rust Playbook] ************************************************************************************* TASK [Gathering Facts] *********************************************************************************** ok: [going-merry] TASK [Install Rust] ************************************************************************************** changed: [going-merry] PLAY RECAP *********************************************************************************************** going-merry : ok=2 changed=1 unreachable=0 failed=0 ``` Now I can use `rustc` on the VM: ```bash ./shipyard ssh going-merry Linux going-merry 4.9.0-8-amd64 #1 SMP Debian 4.9.130-2 (2018-10-27) x86_64 The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. Last login: Wed Nov 28 23:17:19 2018 from 192.168.121.1 vagrant@going-merry:~$ whereis rustc rustc: /usr/bin/rustc /usr/share/rustc /usr/share/man/man1/rustc.1.gz vagrant@going-merry:~$ logout Connection to 192.168.121.89 closed. ```