Commit 45d30d5a authored by Noe Nieto's avatar Noe Nieto 💬
Browse files

Update README.md and fix a couple of typos

parent 5d4cab06
# The shipyard
The `shipyard` is a small wrapper around vagrant/libvirt that allows you to spin new vagrant vms easily, you only need to provide a name and the shipyard builds that vm for you.
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.
## Usage
First you need to setup you machine. Use the `shipyard_setup` script [here first](../start-here).
## Installation
Clone this repo `cd` into it, and launch the command:
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 --name hello-world
./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 <N/A>
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 <N/A>
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.
$
```
Vagrant will start shortly and you can see the output from vagrant.
Now `status` shows that the vm is running.
```
$ shipyard status
hostname State IP Address
usoland shutoff 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 <N/A>
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.
```
......@@ -117,11 +117,10 @@ def create_box(hostname, ram, cpus):
cpus=cpus,
))
# The Ansible shim
vagrant_wd.joinpath('shim.tml').open(mode='w').write(ansible_shim)
vagrant_wd.joinpath('shim.yml').open(mode='w').write(ansible_shim)
# Execute vagrant with the generated vagrantfile
subprocess.run(['vagrant','up'], cwd=vagrant_wd)
subprocess.run(['vagrant','provision'], cwd=vagrant_wd)
@only_if_box_exist
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment