uncloud/ucloud/docs/source/introduction/installation.rst

Installation
============
This guides includes two type of installation

* File System as Image Storage + Level 2 Network without IPAM and Routing
* CEPH as Image Storage + Level 2 Network with automatic IPAM and Routing
  (using Router Advertisement + Netbox)

The guide will explicitly mention a section/subsection if it is exclusive to any
one of the above mentioned scenario.


.. note::
    The instructions assumes the following things
    
    * User is **root**.
    * Base Directory is :file:`/root/`.

Alpine
------

.. note::
    Python Wheel (Binary) Packages does not support Alpine Linux as it is
    using musl libc instead of glibc. Therefore, expect longer installation
    times than other linux distributions.

Enable Edge Repos, Update and Upgrade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warning::
    The below commands would overwrite your repositories sources and
    upgrade all packages and their dependencies to match those available
    in edge repos. **So, be warned**

.. code-block:: sh
    :linenos:

    cat > /etc/apk/repositories << EOF
    http://dl-cdn.alpinelinux.org/alpine/edge/main
    http://dl-cdn.alpinelinux.org/alpine/edge/community
    http://dl-cdn.alpinelinux.org/alpine/edge/testing
    EOF

    apk update
    apk upgrade

    reboot


Install Dependencies
~~~~~~~~~~~~~~~~~~~~
.. note::
    The installation and configuration of a production grade etcd cluster
    is out of scope of this manual. So, we will install etcd with default
    configuration.

.. code-block:: sh
    :linenos:

    apk add git python3 alpine-sdk python3-dev etcd etcd-ctl openntpd \
            libffi-dev openssl-dev make py3-protobuf py3-tempita chrony

    pip3 install pipenv


**Install QEMU (For Filesystem based Installation)**

.. code-block:: sh

    apk add qemu qemu-system-x86_64 qemu-img

**Install QEMU/CEPH/radvd (For CEPH based Installation)**

.. code-block:: sh

    $(git clone https://code.ungleich.ch/ahmedbilal/qemu-with-rbd-alpine.git && cd qemu-with-rbd-alpine && apk add apks/*.apk --allow-untrusted)
    apk add ceph radvd

Syncronize Date/Time
~~~~~~~~~~~~~~~~~~~~

.. code-block:: sh
    :linenos:

    service chronyd start
    rc-update add chronyd


Start etcd and enable it
~~~~~~~~~~~~~~~~~~~~~~~~

.. note::
    The following :command:`curl` statement shouldn't be run once
    etcd is fixed in alpine repos.

.. code-block:: sh
    :linenos:

    curl https://raw.githubusercontent.com/etcd-io/etcd/release-3.4/etcd.conf.yml.sample -o /etc/etcd/conf.yml
    service etcd start
    rc-update add etcd


Install uotp
~~~~~~~~~~~~

.. code-block:: sh
    :linenos:

    git clone https://code.ungleich.ch/ungleich-public/uotp.git
    cd uotp
    mv .env.sample .env

    pipenv --three --site-packages
    pipenv install
    pipenv run python app.py

Run :code:`$(cd scripts && pipenv run python get-admin.py)` to get
admin seed. A sample output

.. code-block:: json

    {
        "seed": "FYTVQ72A2CJJ4TB4",
        "realm": ["ungleich-admin"]
    }

Now, run :code:`pipenv run python scripts/create-auth.py FYTVQ72A2CJJ4TB4`
(Replace **FYTVQ72A2CJJ4TB4** with your admin seed obtained in previous step).
A sample output is as below. It shows seed of auth.

.. code-block:: json

    {
        "message": "Account Created",
        "name": "auth",
        "realm": ["ungleich-auth"],
        "seed": "XZLTUMX26TRAZOXC"
    }

.. note::
    Please note both **admin** and **auth** seeds as we would need them in setting up ucloud.


Install and configure ucloud
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: sh
    :linenos:

    git clone https://code.ungleich.ch/ucloud/ucloud.git
    cd ucloud
    
    pipenv --three --site-packages
    pipenv install

**Filesystem based Installation**

You just need to update **AUTH_SEED** in the below code to match your auth's seed.

.. code-block:: sh
    :linenos:

    mkdir /etc/ucloud

    cat > /etc/ucloud/ucloud.conf << EOF
    AUTH_NAME=auth
    AUTH_SEED=XZLTUMX26TRAZOXC
    AUTH_REALM=ungleich-auth

    REALM_ALLOWED = ["ungleich-admin", "ungleich-user"]

    OTP_SERVER="http://127.0.0.1:8000/"

    ETCD_URL=localhost

    STORAGE_BACKEND=filesystem

    BASE_DIR=/var/www
    IMAGE_DIR=/var/image
    VM_DIR=/var/vm

    VM_PREFIX=/v1/vm/
    HOST_PREFIX=/v1/host/
    REQUEST_PREFIX=/v1/request/
    FILE_PREFIX=/v1/file/
    IMAGE_PREFIX=/v1/image/
    IMAGE_STORE_PREFIX=/v1/image_store/
    USER_PREFIX=/v1/user/
    NETWORK_PREFIX=/v1/network/

    ssh_username=meow
    ssh_pkey="~/.ssh/id_rsa"

    VXLAN_PHY_DEV="eth0"

    EOF



**CEPH based Installation**
You need to update the following

* **AUTH_SEED**
* **NETBOX_URL**
* **NETBOX_TOKEN**
* **PREFIX**
* **PREFIX_LENGTH**


.. code-block:: sh
    :linenos:

    mkdir /etc/ucloud

    cat > /etc/ucloud/ucloud.conf << EOF
    AUTH_NAME=auth
    AUTH_SEED=XZLTUMX26TRAZOXC
    AUTH_REALM=ungleich-auth

    REALM_ALLOWED = ["ungleich-admin", "ungleich-user"]

    OTP_SERVER="http://127.0.0.1:8000/"

    ETCD_URL=localhost

    STORAGE_BACKEND=ceph

    BASE_DIR=/var/www
    IMAGE_DIR=/var/image
    VM_DIR=/var/vm

    VM_PREFIX=/v1/vm/
    HOST_PREFIX=/v1/host/
    REQUEST_PREFIX=/v1/request/
    FILE_PREFIX=/v1/file/
    IMAGE_PREFIX=/v1/image/
    IMAGE_STORE_PREFIX=/v1/image_store/
    USER_PREFIX=/v1/user/
    NETWORK_PREFIX=/v1/network/

    ssh_username=meow
    ssh_pkey="~/.ssh/id_rsa"

    VXLAN_PHY_DEV="eth0"

    NETBOX_URL="<url-for-your-netbox-installation>"
    NETBOX_TOKEN="netbox-token"
    PREFIX="your-prefix"
    PREFIX_LENGTH="64"
    EOF


Install and configure ucloud-cli
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: sh
    :linenos:

    git clone https://code.ungleich.ch/ucloud/ucloud-cli.git
    cd ucloud-cli
    pipenv --three --site-packages
    pipenv install

    cat > ~/.ucloud.conf << EOF
    UCLOUD_API_SERVER=http://localhost:5000
    EOF

    mkdir /var/www/

**Only for Filesystem Based Installation**

.. code-block:: sh

    mkdir /var/image/
    mkdir /var/vm/


Environment Variables and aliases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To ease usage of ucloud and its various components put the following in
your shell profile e.g *~/.profile*

.. code-block:: sh

    export OTP_NAME=admin
    export OTP_REALM=ungleich-admin
    export OTP_SEED=FYTVQ72A2CJJ4TB4

    alias ucloud='cd /root/ucloud/ && pipenv run python ucloud.py'
    alias ucloud-cli='cd /root/ucloud-cli/ && pipenv run python ucloud-cli.py'
    alias uotp='cd /root/uotp/ && pipenv run python app.py'

and run :code:`source ~/.profile`