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

     1  # Getting Started
     2  
     3  In this tutorial we'll be:
     4    1. [installing UniK](getting_started_pull.md#installing-unik)
     5    2. [pull a pre-compiled unikernel image from hub.project-unik.io](getting_started_pull.md#pull-an-existing-unik-unikernel-from-httphubproject-unikio)
     6    3. [launching an instance on Virtualbox](getting_started_pull.md#run-an-instance-of-the-image-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
    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. 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    * Using a text editor, create and save the following to `$HOME/.unik/daemon-config.yaml`:
    46    ```yaml
    47    providers:
    48      virtualbox:
    49        - name: my-vbox
    50          adapter_type: host_only
    51          adapter_name: NEW_HOST_ONLY_ADAPTER
    52    ```
    53    replacing `NEW_HOST_ONLY_ADAPTER` with the name of the network adapter you created.
    54  
    55  
    56  4. Launch UniK and automatically deploy the *Virtualbox Instance Listener*
    57    * Open a new terminal window/tab. This terminal will be where we leave the UniK daemon running.
    58    * `cd` to the `_build` directory created by `make`
    59    * run `unik daemon --debug` (the `--debug` flag is optional, if you want to see more verbose output)
    60    * 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 instance ips and bootstrap instances running on Virtualbox.
    61    * After this is finished, UniK is running and ready to accept commands.
    62    * Open a new terminal window and type `unik target --host localhost` to set the CLI target to the your local machine.
    63  
    64  ---
    65  
    66  #### Pull an existing Unik Unikernel from http://hub.project-unik.io
    67  
    68  0. Open a new terminal window, but leave the window with the daemon running. This window will be used for running UniK CLI commands.
    69  
    70  1. Open another terminal window and type `unik login`
    71  * You will be asked to fill in a URL, Username, and Password. For URL, just hit Enter (this will tell Unik to use the default http://hub.project-unik.io). Pick any username/password you like.
    72  2. List available images with `unik search`
    73  3. Choose an image from the list (by name) and download it to your local storage with `unik pull --image PythonExample --provider virtualbox`
    74  4. Great! Now we're ready to run our first unikernel.
    75  
    76  ---
    77  
    78  #### Run an instance of the image on Virtualbox
    79  
    80  4. Run an instance of this image with
    81    ```
    82    unik run --instanceName myInstance --imageName PythonExample
    83    ```
    84  5. When the instance finishes launching, let's check its IP and see that it is running our application.
    85  6. Run `unik instances`. The instance IP Address should be listed.
    86  7. Direct your browser to `http://instance-ip:8080` and see that your instance is running!
    87  8. To clean up your image and the instance you created
    88    ```
    89    unik rmi --force --image PythonExample
    90    ```