Virtual machine creation
========================

Virtual machine specifications
------------------------------

- **Memory:** 4 GB
- **CPU:** 1 processor, 2 cores
- **Hard Disk:** SCSI, 300 MB
- **CD/DVD**: IDE
- **Network Adapter**: Bridged

In case you're setting up a VMWare virtual machine, select OS type *Other Linux 3.x kernel 64-bit* and after the VM is created, manually edit the ``*.vmx`` file using a text editor and add ``mem.hotadd = "FALSE"``. Failing to do so will result in system unable to boot. Other hypervisors don't need this adjustment.

Virtual machine installation
----------------------------

Note that Alpine is getting new versions fairly quickly. At the time of writing this documentation, 3.11.6 was the latest version, however it's expected that the VM will be kept up-to-date and the instructions written in this document will work even for future versions.

Download **Alpine Virtual x86_64** from https://alpinelinux.org/downloads/ and boot from it. At the login prompt, use the root user without password to log in.

.. code-block:: bash

    # Set up interfaces (leave the default choices)
    setup-interfaces
    ifup eth0

    # Download and launch the setup script
    wget https://repo.spotter.cz/vm.sh
    sh vm.sh

The script will perform installation and configuration of Alpine linux, LXC and the whole VMMgr platform. Virtual machine is protected by LUKS-on-LVM disk encryption. The encryption password, which is simultaneously also a password for VMMgr web administration interface, will be asked for at the beginning of the script execution. Root access on TTY is disabled.

After the script finishes and shuts down the virtual machine, remove CD/DVD drive from the virtual machine settings and extend the HDD to 80 GB. This is to minimize the overall size of the OVA (Open Virtual Appliance) file to which the VM will be exported.

Build environment installation
------------------------------

Follow the VM creation steps as above. Once the VM is built and restarted, log in to the web interface and enter your SSH public key into *authorized_keys* from on ``/setup-apps``. Then log in via SSH.

First time setup
^^^^^^^^^^^^^^^^

.. code-block:: bash

    # Install git and OpenSSH client
    apk add git openssh-client

    # Create SSH key
    ssh-keygen -t ecdsa

Assign the newly generated key to your GitLab account

.. code-block:: bash

    # Clone the repository
    git clone --recursive ssh://git@git.spotter.cz:2222/Spotter-Cluster/Spotter-VM.git

    # Install the build toolchain
    Spotter-VM/build/install-toolchain.sh

Building the packages
^^^^^^^^^^^^^^^^^^^^^

There are 3 distinct packaging systems.

1. Just a plain *tar.gz* for basic OS setup used by ``vm.sh`` installation script.
2. `Abuild <abuild.html>`_ for the native Alpine linux packages (APK) used for ACME client and VMMgr packaging.
3. `SPOC <spoc-overview.html>`_ for SPOC container building and packaging.

Before any building and packaging can be started, build toolchain including signing keys needs to be set up. This is done via ``install-toolchain.sh`` script.

Once the setup is complete, build and packaging can be done manually on per-container basis or a full build of all components can be run via ``build-all.sh`` script. The full build process takes considerable amount of time, so it is advised to have a persistent build VM and rebuild only updated packages.

The ``build-all.sh`` script, resp. most of the build tools it calls, check if the packages they're building have already been built. When a failure occurs and the whole build chain is stopped, rerunning the ``build-all.sh`` will pick up where it left off with very little overhead and will rebuild only the items which have failed, haven't been built yet or have been updated since the last run.
