Setup and Deployment

Production deployment uses Ansible for setting up and configuring a server for EaaSI deployment.

System Requirements

Hardware Requirements

  • A VM or physical machine for the EaaSI gateway (target machine).
  • Minimal/testing:
    • 8-core AMD64 CPU
    • 16 GB RAM
    • 10 GB free disk space for the EaaSI system
    • an additional 100+ GB disk space for resources (Environments, Software, Content), mounted to local file system
  • Recommended:
    • 12-core AMD64 CPU
    • 24 GB RAM
    • 10 GB free disk space for the EaaSI system
    • an additional 300+ GB disk space for resources
    • For VM deployments, support for “Nested KVM”/nested virtualization on the host machine (see KVM Support)
      • If deploying in the cloud, Azure and GCloud VMs should offer this feature out-of-the-box (GCloud users must acknolwedge that the feature is still technically in “beta” first).
      • AWS currently only offers nested virtualization support on its “bare metal” options.
  • A controller machine to run the installation scripts. Typical desktop/laptop hardware is plenty. See below for software requirements.

Software Requirements

  • A supported Linux operating system should be installed on the target machine:
    • Ubuntu 16.04
    • Ubuntu 18.04
    • CentOS 7
  • A python interpreter on the target machine (this should usually be handled automatically on the supported Linux distributions listed above)
  • Docker must be installed on the controller machine. (Installation of Docker and Docker-Compose on the target machine will be automatically handled by the installer, if they are not already present). Please consult Docker’s official documentation to install Docker and Docker Compose on the controller machine before proceeding to installation.

Target Machine Configuration

  • SSH access to the target machine with sudo or root capabilities. Please make sure the target machine user does not need a password to use sudo.
  • EaaSI (as of v2020.03) requires access from the target machine to a SMTP mail server, to handle delivery of user passwords. Either a third-party service (MailGun, SendGrid, AWS, Gmail) or a local option (e.g. a university’s mailing system) should work. Please contact your appropriate IT representative if necessary to obtain the mailer variables listed in Configuring EaaSI-Installer.
  • Certain emulators, such as SheepShaver, require mapping to low memory addresses, which may be disabled by SELinux. If SELinux is enabled, allow mapping low memory addresses by running sudo setsebool -P mmap_low_allowed 1 on the target machine.
  • Make sure that the Docker user has write permission to shared folders.
  • The Docker user must have read/write permissions to /dev/kvm for KVM/nested virtualization support for Environments to work properly.
  • In order to interact and exchange resources with the EaaSI Network, the target machine must be configured at a publicly addressable IP and able to accept HTTP requests.
  • EaaSI specifically retrieves resources from the EaaSI Network via HTTPS, so the machine must also be set up with a valid SSL certificate.

Assumptions

The current version of the EaaSI installer makes the following assumptions:

  • The eaasi-installer depends on the eaasi-ansible repository, which is meant to be used as an EaaSI-specific Ansible library containing a collection of Ansible roles, Docker images and shell-scripts for deploying and configuring Emulation-as-a-Service servers. The installer repository should be viewed as an example for custom deployments. Over time both repositories will be extended and updated to support more deployment setups, based on feedback from users.

  • The target machine will act as an all-in-one installation. This means the UI and several EaaS components will be installed and configured to run from that single machine.

    Note

    eaasi-ansible technically supports distributed deployment, consisting of a single gateway machine and multiple worker machines running emulation sessions. However, this is not yet fully documented and therefore not available in the current installer version.

Installation Procedure

The installation procedure consists of the following steps:

  1. Setting up a controller-machine for running the Ansible-based installer. To minimize platform and version differences of required tools, multiple pre-configured Docker-containers will be built during this step. All tools will be run inside those containers to make the installation procedure more OS agnostic and reproducible. For more details, see Preparing Controller-Machine.
  2. Configuring the installer by specifying the installation target machines and setting options for a customized EaaSI-deployment. For more details, see Configuring EaaSI-Installer.
  3. Deploying EaaSI server (see Running EaaSI-Installer). Here, an Ansible playbook (with custom options from previous step) will be executed. The deployment process is basically composed of the following actions:
    • Preparing target machine, optionally installing Python, Docker and Docker-Compose
    • Downloading pre-built EaaS components from our CI-system
    • Downloading pre-built docker-image containing EaaS runtime
    • Generating deployment-specific EaaS configuration files
    • Starting EaaS container with generated configuration and downloaded components

Preparing Controller-Machine

First, an Ansible controller-machine must be prepared. This controller-machine will coordinate the EaaSI installation process and should preferably use a Linux operating system, but MacOS should also work. To prepare the controller-machine execute the following steps:

  • Clone the eaasi-installer repository into an empty directory. Make sure you have cloned the recommended branch for the current EaaSI release, e.g.:

    $ git clone -b eaasi-release-2020.03 https://gitlab.com/eaasi/eaasi-installer
    
  • Change into this directory and run:

    $ ./scripts/prepare.sh
    

    This script will prepare the repository, build Docker images required for running the installer and generate an SSH key-pair for accessing the target machine. During that process you may be asked for sudo password, depending on your Docker installation.

  • Copy the generated SSH public key to the installation target machine:

    $ ssh-copy-id -i ./artifacts/ssh/admin.key user@hostname
    

    The username should match the remote user with sudo capabilities.

    Note

    If you want to use your own exisiting SSH key, then simply copy the public and private key-pair into the directory ./artifacts/ssh and rename those keys to admin.key and admin.key.pub. Please note, that symbolic links won’t work, because Ansible will be executed in a docker-container, where host’s symbolic links are not valid!

Configuring EaaSI-Installer

The target machines to install EaaSI on should be defined in a file ./artifacts/config/hosts.yaml. You can use the provided template file for a basic configuration:

$ cp ./config/hosts.yaml.template ./artifacts/config/hosts.yaml

Edit this file with a text editor to match your machine, for example:

---
all:
  hosts:
    eaas-gateway:
      ansible_host: my-ubuntu-machine.dns.internal
      ansible_user: ubuntu

Next the EaaSI deployment must be configured in a file ./artifacts/config/eaasi.yaml. As a starting point, you can use the provided template file:

$ cp ./config/eaasi.yaml.template ./artifacts/config/eaasi.yaml

Edit this file with a text editor. An example configuration can look as follows:

---
host:
  build_dir: "/eaasi/build"
  eaas_home: "/eaasi/"

docker:
  image: "eaas/eaas-appserver:eaasi-release-2019-11"
  network_name: "eaasi"

  # to enable SSL with custom certificate,
  # uncomment the following lines...
  #ssl:
  #  enabled: true
  #  certificate: "./artifacts/ssl/certificate.crt"
  #  private_key: "./artifacts/ssl/private.key"

eaas:
  git_branch: "eaasi-release-2019.11"
  enable_oaipmh_provider: true

portal: 
  git_branch: “eaasi-release-2020.03”
  
  auth:
    mailer:
      port: 587
      host: “smtp.example.net”
      user: “admin”
      password: “password”
      sender: “noreply@your-email-domain.com”
  
  organization:
    name: “Your Organization Name”

  initial_user:
    email: “admin@example.com”
    username: “admin”
    first_name: “first name”
    last_name: “last name”

All available configuration options are grouped into 4 sections: host, docker, eaas , portal.

host

Configuration options for the installation target machine.

build_dir
Type:string

An intermediate directory to use during installation.

eaas_home
Type:string

Target directory to install EaaS into.

eaas_tmp
Type:string
Default:/tmp

Directory to store runtime data. (optional)

ssh_port
Type:int

Optional, custom SSH port to use during installation.

docker

Configuration options for the EaaS container.

image
Type:string

Docker image to pull during installation.

network_name
Type:string
Default:eaasi

Name the Docker network created and used for all communication between EaaSI containers. Can be any arbitrary name.

port
Type:int

Optional, custom Docker port to use during installation.

ssl

Optional configuration options for SSL support.

enabled
Type:boolean
Default:false

If true, then the SSL support will be enabled.

certificate
Type:string

A path to a full-chain certificate to use for EaaS service.

Note

Since the installer runs in a Docker container, the certificate file must be located somewhere under ./artifacts on the controller-machine to be available during the installation process.

private_key
Type:string

A path to certificate’s private key. Similar file location restrictions apply, see certificate’s note for more information.

image_archive_volume
Type:string
Default:./image-archive

Optional path to the image archive directory. This path must be writable. If it does not exist, it will be created.

import_volume
Type:string
Default:./import

Optional path to the images import directory.

eaas

Configuration options for the EaaS service.

git_branch
Type:string

Name of the Git branch to install EaaS from.

enable_oaipmh_provider
Type:boolean

Flag to enable export of EaaS environments through an OAI-PMH provider.

portal

Configuration options for the PortalMedia EaaSI User Interface.

git_branch
Type:

string

Git branch name to install EaaSI UI from.

db_update
Type:boolean
Default:false

(Optional) This will remove all current data, if any from the eaasi-database, and perform a clean seed. This optional variable is hidden and defaults to false to prevent accidental deletion of production data. Only set this variable to ``true`` if it is necessary or helpful to perform a clean re-install or update of your node!!!

auth
mailer

SMTP server configuration - required for creating new user accounts (new users will receive an email with their auto-generated password when added by the initial Admin user)

port
Type:int
Default:587

Port for communication with SMTP server (generally either 587 or 465 for SSL-secured connections)

host
Type:string

Host domain or IP address for SMTP mailer.

user
Type:string

Admin username for SMTP mailer.

password
Type:string

Admin password for SMTP mailer.

sender
Type:string

Sender email address for communications from your SMTP mailer (EaaSI users will receive their passwords from this address)

organization
name
Type:string

Organization name for your node (for display in the UI)

initial_user

Configure credentials for initial Admin user in the UI. This user can/must then assign further users using the Manage Node menu.

email
Type:string

The login password for the initial user is hard-coded to “eaasidemo1”. It is strongly recommended that this initial user reset their password (which will generate a random, more secure password). Reset passwords for the initial user will be sent to this address.

username
Type:string

Assign a username to the initial Admin user.

first_name
Type:string

Assign first name for the initial Admin user.

last_name
Type:string

Assign last name for the initial Admin user.

Running EaaSI-Installer

When everything is configured, the installation process can be started by running:

$ ./scripts/deploy.sh

It will take a while depending on your internet connection and target machine. When the installation process is finished, you should be able to access EaaSI with a browser at the URL http://<hostname> (or https://<hostname> if SSL was properly enabled and configured) The <hostname> should match the address of the target machine you specified in the hosts.yaml file. When asked for login credentials, use the email you configured for the intial_user and the password eaasidemo1.

Warning

Again, we strongly recommend the initial user immediately reset their password upon successful login. This will also act as a test of the selected SMTP mailer configuration.

Updating EaaSI

To update a previously-existing EaaSI installation, first update the eaasi-installer by running its git-pull.sh script to match the most up-to-date release provided by the EaaSI team:

$ ./git-pull.sh && ./git-pull.sh origin eaasi-release-2020.03

Note

Running the git-pull.sh script twice, first without arguments, ensures that the script itself is up-to-date first, before fetching the current release branch.

The EaaSI configuration located in artifacts/config/eaasi.yaml must then be updated with the relevant git branch or tag on certain lines as well, for the docker, eaas and portal modules. For the most up-to-date release recommended by EaaSI staff, please use:

  • docker.image: eaas/eaas-appserver:eaasi-release-2019.11
  • eaas.git_branch: eaasi-release-2019.11
  • portal.git_branch: eaasi-release-2020.03

Following these configuration changes, to update the various EaaSI components, run:

$ ./scripts/update.sh [<component>...]

where <component> can be one of the following:

  • ear: to update EaaSI’s server binary to the latest version
  • docker-image: to update runtime docker-image to the latest version
  • ui: to update the PortalMedia UI elements to the latest version

Multiple components can be specified as a space-separated list. If called without any <component> arguments, then all components will be updated by default.

Updates are run selectively in this way due to the way Ansible works: most actions executed during the installation are idempotent and can be repeated multiple times resulting in the same deployment state. This also means certain operations (like downloading files) are skipped, if those files are already present on the target machine. Ansible must be forced to omit the idempotency requirement for certain operations, to be able to update EaaSI’s UI, server binary and runtime docker-image.

Deployment Troubleshooting

If you encounter errors in deploying or updating to EaaSI release 2020.03-beta, the EaaSI team has created a Deployment FAQ/troubleshooting page with possible pitfalls and work-arounds encountered by the development team during testing. This may be of use when working in non-standard network environments in particular.

Please file a ticket if continuing to encounter issues/errors during deployment or updating of your EaaSI node.

Browser Compatibility

The EaaSI team recommends attempting to access the EaaSI UI using:

  • Firefox (v. 65+, possibly a few older versions too)
  • Chrome

All other current browsers - such as Safari or older (non-Chrome-based) versions of Microsoft Edge will work to some degree but are not well tested.

Note

Some browser extensions also may interfere with EaaSI functionality, including ad-blockers, popup-blockers or similar. If encountering unexpected behavior, please try disabling all browser extensions first.