Getting started with emulation – The EaaS Desktop application

Getting started with emulation – The EaaS Desktop application

Emulation-as-a-Service (EaaS) has successfully evolved from the bwFLA project since 2011 and is now in production use. However, setting up a new instance without help of the developers was challenging if not painful. Thankfully, a DGF/NEH grant enabled us to work on usability, documentation and novel workflows, to enable a wider audience to use emulation.

This article describes the EaaS Desktop standalone EaaS application for Windows, Mac and Linux but is also the beginning of a mini series of EaaS/Emulation related blog posts.

The EaaS Desktop docker has been developed to run EaaS as a local application. There are no specific hardware/software requirements beside a working Docker installation (see below). Even though Docker is available for all major operating systems, there are some technical limitations on Windows and Mac hosts:

  • CPU and GPU virtualization is only available on native Linux host with appropriate hardware and software support. For many use-cases this is not an issue but without CPU virtualization (KVM pass-through), but some emulated environments will be very slow (e.g. Windows XP).
  • There might be a performance penalty due to the extra overhead of Docker on non-native Linux system (Docker runs on a virtualized mini-Linux). In particular filesystem performance is prety bad, which is noticable when importing or exporting large images.

The EaaS Desktop application has been developed for test and research purposes but also to prepare content for (publicly) accessible instances. Example scenarios discussed in this and follow-up posts will cover

  • creation of “base environments”, i.e. installing and configuring an operating system within the emulation framework,
  • import and curation of user disk images, e.g. as a result of a BitCurator workflow,
  • creation of “object environments”, a ready-made object specific environment, and
  • export to a kiosk or cloud EaaS instance.

Getting Started

In order to simplify installation and deployment of EaaS, all components are made available as Docker instances. To install EaaS, first install Docker by following the installation guide for your system:

Furthermore, the docker-compose tool is required. It is automatically installed for Windows and Mac users, Linux users should follow these instructions.

Once Docker is up and running, the system is ready to host an EaaS instance. As a next step create a working directory, e.g. eaas-desktop. Within this folder create a file called docker-compose.yaml, which should contain the following content:

version: '2'
services:
  eaas:
    image: eaas/eaas-desktop
    container_name: desktop
    privileged: true # needed to run sheepshaver
    ports:
      # maps eaas service to host port 8080
      - 8080:80
    volumes:
      - ./log:/eaas/log
      # make server-data persistent
      - ./server-data:/eaas/server-data
      # target folder for exported environments
      - ./export:/eaas/export
      # import folder
      - ./import:/eaas/import
      # user objects
      - ./objects:/eaas/objects
      # environmnets and meta-data
      - ./image-archive:/eaas/image-archive
      # roms to be used during import
      - ./roms:/eaas/roms

 

Finally, to run EaaS, open a command line terminal, change in to the eaas-desktop directory (the directory that have been unpacked) and run:

docker-compose up

You should see similar to:

Recreating eaas ...
Recreating eaas ... done
Attaching to eaas
[...]
eaas    | starting deployment. this may take a while...
eaas    |
eaas    | root: Successfully deployed "eaas-server.ear".

The log file of the server can be found in the log subdirectory of the eaas-desktop workdir.

Now, the EaaS instance is running and is reachable through http://localhost:8080/demo-ui/admin. So far, this is a fully functional EaaS instance, however, without content.

Creating Environments

There are two options to create a new environment

  • importing an existing disk image, e.g. from another emulation system or an image of a physical hard disk,
  • create a new virtual disk and install an operating system

This blog post will describe only the second option, import of disk images will be covered in the next post.

As a first step, the operating system to be installed needs to be ingested into the EaaS system. In EaaS terms we distinguish between environments (also sometimes called images) and objects. An environment is a combination of an emulator and typically a disk image containing an installed and configured operating system and additional software. These environments can then be used to render objects, e.g. playing a computer game, running software, rendering documents etc.). Hence, the operating system to be installed is also considered as an object, but with specific features to be exposed to the EaaS framework.

  • Some objects can be considered as software, in EaaS terms such an object is able to render other objects (described by their file formats as Pronom UID) and can be installed into an environment.
  • Some software objects are operating systems, which do not require a pre-existing environment, but are able to run only with a suitable emulator fulfilling their hardware requirements.

Maintaining Objects

Usually, (digital) objects are maintained by dedicated object repositories. For this, EaaS provides adapters to import/export object from/to such repositories and no dedicated UI to import and/or maintain objects. In the default desktop version, digital objects can be maintained manually through a simple file system structure. To make digital objects available within the EaaS framework:

  • Create an objects/ directory within your EaaS working directory
  • Create a new subfolder under objects/ representing both the target folder of an individual object as well as the objects internal ID. Therefore, please avoid using folder names with spaces or exotic (non ASCII) characters.
  • Within the object subdir, create a further subdir, describing the objects individual media types. Currently, supported media types are:
    • iso/ This folder should contain CDROM disk images.
    • disk/ This folder should contain hard disk images.
    • floppy/ This folder should contain floppy disk images.
    • file/ This folder may contain arbitrary files (including subfolder). These files will be wrapped as ISO/CDROM image by default. Note: the folder will not be checked for updated files, i.e. the contents of this folder will not be “repackaged” automatically. To force, repackaging, delete the __imported.iso file in the iso/ folder of the current object.

Available objects will be listed under: http://localhost:8080/.

Note: If you added an object while EaaS was running, the contents of the object archive need to be reloaded. Click “Settings” – “Sync Object Archives”.

Maintaining Software-Objects (incl. Operating Systems)

To use an object as software or operating system, some additional meta-data is required. The demo-ui provides a simple workflows for this task. Click the “Software” link to see the list of available software.

To promote an object to a software object, click “Add new Software”. In the next step an object can be selected and additional metadata can be added. Tick Operating System to indicate this object as an installable operating system. This implies that the object’s file (e.g. ISO or floppies) are bootable. You may also choose a preset for this operating system, i.e. add the OS’s rendering capabilites. In case of MS DOS, the presets will add x-fmt/409 (MS-DOS Executable). This information will be available during object characterization, e.g. if an object contains MS-DOS executables, all environments with an installed MS-DOS operating system will be suggested.

Exercise: Install MS-DOS 6.22

Download floppy images form an abandoned software page (Vetusware or WinWorldPC) or image the original floppies. For this example we found a floppy set containing four disk images.

  • create an MS-DOS_6.22/floppy/ folder in the eaas-desktop/objects directory
  • copy all disk image to this folder. avoid spaces or non-ascii characters and use the .img file extension

The objects should than contain MS-DOS_6.22 subdirectory with the following structure:

MS-DOS_6.22/
      └── floppy
          ├── Disk1.img
          ├── Disk2.img
          ├── Disk3.img
          └── Suppdisk.img

Then add the MS-DOS as a software / operating system object and install:

  • (re-)start EaaS or synchronize the object archive (see above)
  • run the software ingest workflow and mark this object as operating system
  • run the create environment workflow (-> screencast below)

Homework

Play with the EaaS Desktop application and populate your image archive. The upcoming blog posts will cover more (digital object related) workflows. If you do not want to wait, take a look at the EaaS Documentation.

245
reads

10 Comments

  1. thorsted
    September 25, 2017 @ 9:37 pm CEST

    I have installed on Mac OS, but whenever I try and run a Mac System 7 emulator, I get this error. Do I have to to install BasiliskII and Sheepshaver separately?

    eaas-desktop | Sep 25 20:29:19 6088954e9cb3 guacd[19077]: Protocol “sdlonp” selected
    eaas-desktop | Sep 25 20:29:19 6088954e9cb3 guacd[19077]: Connection ID is “$54862ccf-916f-4f8d-8e81-8720e31f0dfa”
    eaas-desktop | Sep 25 20:29:34 6088954e9cb3 guacd[19077]: Emulator’s IO-socket ‘/tmp/91800188446430622/sdlonp-iosocket-emu’ was not found.
    eaas-desktop | Sep 25 20:29:34 6088954e9cb3 guacd[19077]: Unable to connect to the emulator.
    eaas-desktop | Sep 25 20:29:34 6088954e9cb3 guacd[19077]: Connection did not succeed

  2. klaus
    September 16, 2017 @ 7:52 pm CEST

    That should work as well in principle. Can’t spot an obvouis error. Could you please update the container

    docker pull eaas/eaas-desktop

    and if the error reappears, please open the Js/Web console in your browser (e.g. press F12 in Firefox) c&p the error message(s).

  3. prader
    September 15, 2017 @ 9:57 pm CEST

    If one didn’t want to use docker-compose can you see why this command wouldn’t work? There do not appear to be permissions issues.

    docker run -d –name=”eaas-desktop” –net=”bridge” –privileged=”true” -e TZ=”America/New_York” -e “PUID”=”99 ” -e “PGID”=”100” -p 8080:80/tcp -v “/mnt/disks/Intel/appdata/eaas.log”:”/eaas/log”:rw,slave -v “/mnt/disks/Intel/appdata/eaas/export”:”/eaas/export”:rw,slave -v “/mnt/disks/Intel/appdata/eaas/import”:”/eaas/import”:rw,slave -v “/mnt/disks/Intel/appdata/eaas/objects”:”/eaas/objects”:rw,slave -v “/mnt/disks/Intel/appdata/eaas/image-archive”:”/eaas/image-archive”:rw,slave -v “/mnt/disks/Intel/appdata/eaas/server-data”:”/eaas/server-data”:rw,slave eaas/eaas-desktop

  4. klaus
    September 15, 2017 @ 9:08 pm CEST

    Do a

    docker-compose pull

    to retrieve the most current version. If you still see the error, please open the JavaScript console in your browser and paste the error (CORS? / Browser-Extension?)

  5. prader
    September 15, 2017 @ 8:40 pm CEST

    Hi,
    I tried following this, but it seems to error during.

    *** Running /etc/my_init.d/00_regen_ssh_host_keys.sh…
    *** Running /etc/my_init.d/10_mount_volumes.sh…
    mount server-data
    mounting imagearchive
    mount objects
    mount export
    mount import
    mounting demo-ui
    *** Running /etc/my_init.d/90_sheepshaver-sysctl.sh…
    vm.mmap_min_addr = 0
    *** Running /etc/rc.local…
    *** Booting runit daemon…
    *** Runit started as PID 36
    warning: eaas: unable to open supervise/ok: file does not exist

    Sep 15 18:55:14 60bae7b0edd9 syslog-ng[46]: syslog-ng starting up; version=’3.5.6′

    ok: run: eaas: (pid 53) 2s
    ok: run: syslog-ng: (pid 46) 3s
    starting deployment. this may take a while…
    Sep 15 18:55:28 60bae7b0edd9 root: Successfully deployed “eaas-server.ear”.
    Sep 15 19:17:01 60bae7b0edd9 CRON[577]: (root) CMD ( cd / && run-parts –report /etc/cron.hourly)

    If I browse to web GUI I get:
    “The EAAS service is currently not ready. As soon as it becomes ready you can automatically resume.”

    Any thoughts?

Leave a Reply

Join the conversation