Base Image Installation

The Appliance Base Image can install the Anapaya Appliance on bare metal or as a VM running on a hypervisor. The minimal system requirements are described in the Computing resources guide. The base image is provided in three different formats: (1) a qcow2 image or a (2) VMDK image purposed for a fast setup of VM’s, and (3) an ISO image that can be used to provision bare metal machines.

The images are hosted on cloudsmith.io. To download them, two pieces of information are required:

  • Access token

    The access token is provided to you by Anapaya as part of your software license.

  • Base image version

Note

In the following commands, the variables ($VERSION, $ACCESS_TOKEN) must be replaced with the actual values. The version uniquely identifies the base image release. You may find the latest releases on the release notes page.

We recommend setting the variables as environment variables

export ACCESS_TOKEN=xxxxxxx
export VERSION=v0.XX.Y

or replace the variables directly in the commands.

By providing the values here, the commands are automatically updated with the correct values.

Version:

To download the ISO or qcow2 images, use the following commands:

# ISO Image
wget https://dl.cloudsmith.io/$ACCESS_TOKEN/anapaya/stable/raw/names/anapaya-appliance-base/versions/$VERSION_PH/anapaya-appliance-base-$VERSION_PH.iso
# QCOW2 BIOS Version
wget https://dl.cloudsmith.io/$ACCESS_TOKEN/anapaya/stable/raw/names/anapaya-appliance-base-bios-qcow2/versions/$VERSION_PH/anapaya-appliance-base-$VERSION_PH-bios.qcow2
# QCOW2 UEFI Version
wget https://dl.cloudsmith.io/$ACCESS_TOKEN/anapaya/stable/raw/names/anapaya-appliance-base-uefi-qcow2/versions/$VERSION_PH/anapaya-appliance-base-$VERSION_PH-uefi.qcow2
# VMDK UEFI Version
wget https://dl.cloudsmith.io/$ACCESS_TOKEN/anapaya/stable/raw/names/anapaya-appliance-base-uefi-vmdk/versions/$VERSION_PH/anapaya-appliance-base-$VERSION_PH-uefi.vmdk

Verify that the checksum of the downloaded image matches the one documented on the release notes page:

sha256sum <IMAGE>

Note

Anapaya recommends to use UEFI images for new installations. Make sure to change the BIOS settings to UEFI boot mode on the target machine. The BIOS image is still available for legacy platforms.

Note

The Anapaya Appliance Base Image is a full system image that includes all the necessary modules to bootstrap an Anapaya Appliance instance. The system image is hardened by Anapaya. However, the configuration and hardening of the host or hypervisor that hosts the Anapaya Appliance is the responsibility of the user. Please refer to the corresponding vendor guidelines and best practices.

Install the base image on a hypervisor

  1. Copy the qcow2 image to the hypervisor and install it according to the platform documentation.

  2. Allocate resources to the Anapaya Appliance (at least 4G of RAM and 2-4 vCPUs) and then boot the VM.

Install the base image on bare metal

Create bootable USB installer on Ubuntu

  1. Insert a USB drive and find its device name path (e.g. /dev/sdb) by running the following command (look for type disk):

    lsblk

  2. Unmount the USB device in case it is mounted, by running:

    sudo umount /dev/<usb-dev>

  3. Burn the ISO to the USB drive

    sudo dd bs=4M if=<path-to-iso> of=/dev/<usb-dev> status=progress oflag=sync conv=fsync

Warning

Installing the base image with a network cable plugged-in can cause issues during the installation. We recommend to unplug the network cable during the installation.

Note

If your machine is running Windows or macOS or you prefer a GUI, you can download a tool such as Etcher, to burn the ISO image to a USB drive to complete this step.

Configure the installer

In this optional step, you can configure the installer such that no interaction is required after initiating the boot.

  1. To store the base installer user configuration on the USB drive, mount the third partition of the USB device, by running:

    sudo mount /dev/<usb-dev>3 /mnt

  2. Create an installer configuration file at /mnt/anapaya-user-config.yaml containing the boot disk name, and a parameter poweroff_final to make the machine power off, once the installation has been completed.

    The most critical part is the disk configuration. To verify the storage deivce name you can run the following command on the target machine:

    lsblk

    In the generic case the disk name is sda.

    disk: sda poweroff_final: true

However, it can be different, generally they follow the naming convention sda, sdb, nvme0n1 etc.

(Device Names in Linux)

For our explicitly supported devices we provide the following recommended configurations:

Appliance S-Type Lanner

disk: "sda"
poweroff_final: true

Appliance L-Type Supermicro

disk: "sda"
secondary_disk: "sdb"
poweroff_final: true

Appliance XL-Type Supermicro

disk: "sda"
secondary_disk: "sdb"
poweroff_final: true

There are a few more parameters that can be configured depending on your setup. Only set the listed parameters if you are sure you need to change the default value.

installer parameters:

# Hostname: the target system's hostname.
hostname: anapaya-appliance
# User: the default user name
user: anapaya
# Password: the default user password.
password: anapaya
# InteractiveNetworkSetup: If non-interactive network setup, the installer configures IPv4 DHCP on all interfaces.
interactive_network_setup: false
# Disk: the system's disk name to install the software (default not set).
# When no disk is configured, it implies interactive storage setup which is the
# default behavior.
# Based on the disk size, the layout would be as follow:
# - < 12GB: not supported
# - < 20GB: 8GB root lvm partition, leftover space for the var lvm partition
# - < 40GB: 16GB root lvm partition, leftover space for the var lvm partition
# - >= 40GB: 24GB root lvm partition, leftover space for the var lvm partition
disk: sde
# SecondaryDisk: If a secondary disk is specified it will be used for the systems /var directory.
# The root lvm partition will use the entirety of the primary disk in this case.
secondary_disk: sdb
# PowerOffPreBoot: when `true`, it will shutdown the system before the first boot.
poweroff_preboot: false
# PowerOffFinal: when `true`, it will shutdown the system after the installation has completed.
poweroff_final: false

  1. Unmount the third partition, by running:

    sudo umount /dev/<usb-dev>3 /mnt

Boot from the installer

Insert the USB media into the target system and initiate the boot sequence by powering on the machine.

Note

It might be necessary to change the boot order preference settings in the BIOS of the machine to favour USB devices.

If you added a configuration to the installer, the installation will start automatically, otherwise you need to select the installation target disk manually. During the installation process, the machine will restart a few times.

Note

During the final step of the installation, the OS is booted and a login prompt appears. To check the installation progress you can authenticate with the default credentials, or the credentials that were configured and run:

watch cloud-init status

After the installation has completed, the machine shuts itself down.

Next steps

You are now ready to provision the Anapaya Appliance. A good place to start is the Anapaya Appliance getting started guide. If you are already familiar with the appliance configuration, you can also use the Appliance Configuration Reference to set up and configure the appliance.