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

     1  # Getting Started
     2  
     3  In this tutorial we'll be:
     4    1. [installing UniK](getting_started_python3.md#installing-unik)
     5    2. [writing a simple HTTP Daemon in Python](getting_started_python3.md#write-a-python-http-server)
     6    3. [compiling to a unikernel and launching an instance on Virtualbox](getting_started_python3.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    * `cd` to the `_build` directory created by `make`
    57    * run `./unik daemon --debug` (the `--debug` flag is optional, if you want to see more verbose output)
    58    * 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.
    59    * After this is finished, UniK is running and ready to accept commands.
    60    * Open a new terminal window and type `unik target --host localhost` to set the CLI target to the your local machine.
    61  
    62  ---
    63  
    64  #### Write a Python HTTP server
    65  1. Open a new terminal window, but leave the window with the daemon running. This window will be used for running UniK CLI commands.
    66  
    67  2. Make sure `python3.5` and `pip` are installed:
    68    * Python 3.5: https://www.python.org/downloads/release/python-351/
    69    * Pip (for OS X): http://softwaretester.info/install-and-upgrade-pip-on-mac-os-x/
    70    * Pip (Ubuntu): http://www.saltycrane.com/blog/2010/02/how-install-pip-ubuntu/ (on Ubuntu/Debian)
    71  
    72  3. Create a file `server.py` using a text editor. Copy and paste the following code in that file:
    73  
    74    ```python
    75    import http.server
    76    import socketserver
    77  
    78    PORT = 8080
    79  
    80    Handler = http.server.SimpleHTTPRequestHandler
    81  
    82    httpd = socketserver.TCPServer(("", PORT), Handler)
    83  
    84    print("serving at port", PORT)
    85    httpd.serve_forever()
    86  
    87    ```
    88  
    89    This will be our simple Python server.
    90  
    91    *Note*: dependencies in Python applications must be installed with `pip` to the project directory (rather than the global `site-packages` for the current user). See [rump-python3](compilers/rump.md#python-3) for more information.
    92  
    93  4. Try running this code with `python3 server.py`. Visit [http://localhost:8080/](http://localhost:8080/) to see that the server is running.
    94  
    95  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.py`.
    96  
    97    * Create a file named `manifest.yaml` and paste the following inside:
    98    ```yaml
    99    main_file: server.py
   100    ```
   101  
   102  6. Great! Now we're ready to compile this code to a unikernel.
   103  
   104  ---
   105  
   106  #### Compile an image and run on Virtualbox
   107  
   108  1. run the following command from the directory where your `server.py` is located:
   109    ```
   110    unik build --name myImage --path ./ --base rump --language python --provider virtualbox
   111    ```
   112    this command will instruct UniK to compile the sources found in the working directory (`./`) using the `rump-python-virtualbox` compiler.
   113  
   114  2. You can watch the output of the `build` command in the terminal window running the daemon.
   115  
   116  3. When `build` finishes, the resulting disk image will reside at `$HOME/.unik/virtualbox/images/myImage/boot.vmdk`
   117  
   118  4. Run an instance of this image with
   119    ```
   120    unik run --instanceName myInstance --imageName myImage
   121    ```
   122  
   123  5. When the instance finishes launching, let's check its IP and see that it is running our application.
   124  
   125  6. Run `unik instances`. The instance IP Address should be listed.
   126  
   127  7. Direct your browser to `http://instance-ip:8080` and see that your instance is running!
   128  
   129  8. To clean up your image and the instance you created
   130    ```
   131    unik rmi --force --image myImage
   132    ```