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

     1  # Getting Started
     2  
     3  In this tutorial we'll be:
     4    1. [installing UniK](getting_started_node.md#installing-unik)
     5    2. [writing a simple HTTP Daemon in Nodejs](getting_started_node.md#write-a-nodejs-http-server)
     6    3. [compiling to a unikernel and launching an instance on Virtualbox](getting_started_node.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
    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  3. Configure UniK daemon
    44    * Using a text editor, create and save the following to `$HOME/.unik/daemon-config.yaml`:
    45    ```yaml
    46    providers:
    47      virtualbox:
    48        - name: my-vbox
    49          adapter_type: host_only
    50          adapter_name: NEW_HOST_ONLY_ADAPTER
    51    ```
    52    replacing `NEW_HOST_ONLY_ADAPTER` with the name of the network adapter you created.
    53  
    54  4. Launch UniK and automatically deploy the *Virtualbox Instance Listener*
    55    * Open a new terminal window/tab. This terminal will be where we leave the UniK daemon running.
    56    * run `unik daemon --debug` (the `--debug` flag is optional, if you want to see more verbose output)
    57    * 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.
    58    * After this is finished, UniK is running and ready to accept commands.
    59    * Open a new terminal window and type `unik target --host localhost` to set the CLI target to the your local machine.
    60  
    61  ---
    62  
    63  #### Write a Node.js HTTP server
    64  1. Open a new terminal window, but leave the window with the daemon running. This window will be used for running UniK CLI commands.
    65  
    66  2. Make sure `Node` and `npm` are installed:
    67    * http://blog.teamtreehouse.com/install-node-js-npm-mac (on OS X)
    68    * https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-an-ubuntu-14-04-server (on Ubuntu/Debian)
    69  
    70  3. Create a file `server.js` using a text editor. Copy and paste the following code in that file:
    71  
    72    ```javascript
    73    var express    = require('express');
    74    var app = express();
    75    var directory = require('serve-index');
    76  
    77    app.use(express.static('./'));
    78    app.use(directory('./'));
    79    app.listen("8080");
    80    ```
    81  
    82    This will be our simple Nodejs server.
    83  
    84  4. Use `npm` to install the dependency for our app, `express.js`:
    85    ```bash
    86    npm install express serve-index
    87    ```
    88  
    89    Try running this code with `node server.js`. Visit [http://localhost:8080/](http://localhost:8080/) to see that the server is running.
    90  
    91      *Note:* for Node.js projects with imported dependencies, you will need to install npm and run `npm install <package_name>` for each package your application requires. See [Compiling Node.js Apps with UniK](compilers/rump.md#nodejs) for more information.
    92  
    93  5. We need to create a manifest file to tell UniK the name of the file which contains the entrypoint to our application. In this case, it's just `server.js`.
    94  
    95    * Create a file named `manifest.yaml` and paste the following inside:
    96    ```yaml
    97    main_file: server.js
    98    ```
    99  
   100  6. Great! Now we're ready to compile this code to a unikernel.
   101  
   102  ---
   103  
   104  #### Compile an image and run on Virtualbox
   105  
   106  1. run the following command from the directory where your `server.js` is located:
   107    ```
   108    unik build --name myImage --path ./ --base rump --language nodejs --provider virtualbox
   109    ```
   110    this command will instruct UniK to compile the sources found in the working directory (`./`) using the `rump-nodejs-virtualbox` compiler.
   111  
   112  2. You can watch the output of the `build` command in the terminal window running the daemon.
   113  
   114  3. When `build` finishes, the resulting disk image will reside at `$HOME/.unik/virtualbox/images/myImage/boot.vmdk`
   115  
   116  4. Run an instance of this image with
   117    ```
   118    unik run --instanceName myInstance --imageName myImage
   119    ```
   120  
   121  5. When the instance finishes launching, let's check its IP and see that it is running our application.
   122  
   123  6. Run `unik instances`. The instance IP Address should be listed.
   124  
   125  7. Direct your browser to `http://instance-ip:8080` and see that your instance is running!
   126  
   127  8. To clean up your image and the instance you created
   128    ```
   129    unik rmi --force --image myImage
   130    ```