github.com/emc-advanced-dev/unik@v0.0.0-20190717152701-a58d3e8e33b7/docs/getting_started.md (about)

     1  # Getting Started
     2  
     3  In this tutorial we'll be:
     4    1. [installing UniK](getting_started.md#installing-unik)
     5    2. [writing a simple HTTP Daemon in Go](getting_started.md#write-a-go-http-server)
     6    3. [compiling to a unikernel and launching an instance on Virtualbox](getting_started.md#compile-an-image-and-run-on-virtualbox)
     7  
     8  ### Installing UniK
     9  #### Prerequisites
    10  Ensure that each of the following are installed
    11  - [Docker](http://www.docker.com/) installed and running with at least 6GB available space for building images
    12  - [`jq`](https://stedolan.github.io/jq/)
    13  - [`make`](https://www.gnu.org/software/make/)
    14  - [Virtualbox](https://www.virtualbox.org/)
    15  
    16  #### Install, configure, and launch UniK
    17  1. Install UniK
    18    ```
    19    $ git clone https://github.com/solo-io/unik.git
    20    $ cd unik
    21    $ make binary
    22    ```
    23    note: `make` will take quite a few minutes the first time it runs. the UniK `Makefile` is pulling all of the Docker images that bundle UniK's dependencies.
    24  
    25    Then, place the `unik` executable in your `$PATH` to make running UniK commands easier:
    26    ```
    27    $ mv _build/unik /usr/local/bin/
    28    ```
    29  
    30  2. Configure a Host-Only Network on Virtualbox
    31    * Open Virtualbox
    32    * Open **Preferences** > **Network** > **Host-only Networks**
    33    * Click the green add button on the right side of the UI
    34    * Record the name of the new Host-Only adapter (e.g. "vboxnet0"). You will need this in your UniK configuration
    35    * Ensure that the Virtualbox DHCP Server is Enabled for this Host-Only Network:
    36      * With the Host-Only Network selected, Click the edit button (screwdriver image)
    37      * In the **Adapter** tab, note the IPv4 address and netmask of the adapter.
    38      * In the **DHCP Server** tab, check the **Enable Server** box
    39      * Set **Server Address** an IP on the same subnet as the Adapter IP. For example, if the adapter IP is `192.168.100.1`, make set the DHCP server IP as `192.168.100.X`, where X is a number between 2-254.
    40      * Set **Server Mask** to the netmask you just noted
    41      * Set **Upper / Lower Address Bound** to a range of IPs on the same subnet. We recommend using the range `X-254` where X is one higher than the IP you used for the DHCP server itself. E.g., if your DHCP server is `192.168.100.2`, you can set the lower and upper bounds to `192.168.100.3` and `192.168.100.254`, respectively.
    42  
    43  
    44  3. Configure UniK daemon
    45    * UniK configuration files are stored in `$HOME/.unik`. Create this directory, if it is not present:
    46    ```
    47    $mkdir $HOME/.unik
    48    ```
    49    * Using a text editor, create and save the following to `$HOME/.unik/daemon-config.yaml`:
    50    ```yaml
    51    providers:
    52      virtualbox:
    53        - name: my-vbox
    54          adapter_type: host_only
    55          adapter_name: NEW_HOST_ONLY_ADAPTER
    56    ```
    57    replacing `NEW_HOST_ONLY_ADAPTER` with the name of the network adapter you created.
    58  
    59  
    60  4. Launch UniK and automatically deploy the *Virtualbox Instance Listener*
    61    * Open a new terminal window/tab. This terminal will be where we leave the UniK daemon running.
    62    * `cd` to the `_build` directory created by `make`
    63    * run `unik daemon --debug` (the `--debug` flag is optional, if you want to see more verbose output)
    64    * UniK will compile and deploy its own 30 MB unikernel. This unikernel is the [Unik Instance Listener](./instance_listener.md). The Instance Listener uses udp broadcast to detect (the IP address) and bootstrap instances running on Virtualbox.
    65    * After this is finished, UniK is running and ready to accept commands.
    66    * Open a new terminal window and type `unik target --host localhost` to set the CLI target to the your local machine.
    67  
    68  ---
    69  
    70  #### Write a Go HTTP server
    71  
    72  0. Open a new terminal window, but leave the window with the daemon running. This window will be used for running UniK CLI commands.
    73  
    74  1. Create a file `httpd.go` using a text editor. Copy and paste the following code in that file:
    75  
    76    ```go
    77    package main
    78  
    79    import (
    80        "fmt"
    81        "net/http"
    82    )
    83  
    84    func main() {
    85        http.HandleFunc("/", handler)
    86        http.ListenAndServe(":8080", nil)
    87    }
    88  
    89    func handler(w http.ResponseWriter, r *http.Request) {
    90        fmt.Fprintf(w, "my first unikernel!")
    91    }
    92    ```
    93  
    94  2. Try running this code with `go run httpd.go`. Visit [http://localhost:8080/](http://localhost:8080/) to see that the server is running.
    95  3. We need to create a dummy `Godeps` file. This is necessary to tell the Go compiler how Go projects and their dependencies are structured. Fortunately, with this example, our project has no dependencies, and we can just fill out a simple `Godeps` file without installing [`godep`](https://github.com/tools/godep). Note: for Go projects with imported dependencies, and nested packages, you will need to install Godeps and run `GO15VENDOREXPERIMENT=1 godep save ./...` in your project. See [Compiling Go Apps with UniK](compilers/rump.md#golang) for more information.
    96    * To create the dummy Godeps file, create a folder named `Godeps` in the same directory as `httpd.go`. Inside, create a file named `Godeps.json` and paste the following inside:
    97    ```json
    98    {
    99    	"ImportPath": "my_httpd",
   100    	"GoVersion": "go1.6",
   101    	"GodepVersion": "v63",
   102    	"Packages": [
   103    		"./.."
   104    	],
   105    	"Deps": [
   106    		{
   107    			"ImportPath": "github.com/solo-io/unik/docs/examples",
   108    			"Rev": "f8cc0dd435de36377eac060c93481cc9f3ae9688"
   109    		}
   110    	]
   111    }
   112    ```
   113    * For the purposes of this example, that matters here is `my_httpd`. It instructs the go compiler that the project should be installed from `$GOPATH/src/my_httpd`.
   114  
   115  4. Great! Now we're ready to compile this code to a unikernel.
   116  
   117  ---
   118  
   119  #### Compile an image and run on Virtualbox
   120  
   121  1. run the following command from the directory where your `httpd.go` is located:
   122    ```
   123    unik build --name myImage --path ./ --base rump --language go --provider virtualbox
   124    ```
   125    This command will instruct UniK to compile the sources found in the working directory (`./`) using the `rump-go-virtualbox` compiler.
   126  2. You can watch the output of the `build` command in the terminal window running the daemon.
   127  3. When `build` finishes, the resulting disk image will reside at `$HOME/.unik/virtualbox/images/myImage/boot.vmdk`
   128  4. Run an instance of this image with
   129    ```
   130    unik run --instanceName myInstance --imageName myImage
   131    ```
   132  5. When the instance finishes launching, let's check its IP and see that it is running our application.
   133  6. Run `unik instances`. The instance IP Address should be listed.
   134  7. Direct your browser to `http://instance-ip:8080` and see that your instance is running!
   135  8. To clean up your image and the instance you created
   136    ```
   137    unik rmi --force --image myImage
   138    ```