Getting started with emulation – The EaaS Desktop application

Quattro Pro for DOS: an obsolete format at last?

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'
    image: eaas/eaas-desktop
    container_name: desktop
    privileged: true # needed to run sheepshaver
      # maps eaas service to host port 8080
      - 8080:80
      - ./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:

      └── 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)


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.



  1. neelofar
    November 3, 2017 @ 3:57 am CET

    Does anyone have luck to install any mac version successfully? I am getting this error consistently what ever version I try to install

    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-EVENTS] Emulator’s keyboard layout: us
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-EVENTS] Client’s keyboard model: pc105
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-EVENTS] Client’s keyboard layout: us
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-VIDEO] SDLONP video-driver was initialized successfully.
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-AUDIO] Initializing SDLONP audio-driver…
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 guacd[845]: Protocol “sdlonp” selected
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-AUDIO] SDLONP audio-driver was initialized successfully.
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-AUDIO] Deleting SDLONP audio-driver…
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-AUDIO] SDLONP audio-driver deleted.
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-VIDEO] Closing SDLONP video-driver…
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-VIDEO] SDLONP video-driver closed.
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-VIDEO] Deleting SDLONP video-driver…
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-VIDEO] Shared data cleaned up.
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 SheepShaver: [SDLONP-VIDEO] SDLONP video-driver deleted.
    eaas-desktop | Nov 3 03:50:17 7d95fa9ee591 guacd[845]: Connection ID is “$bbf7ef64-640a-4e86-9d58-da2c5f98b303”
    eaas-desktop | Nov 3 03:50:33 7d95fa9ee591 guacd[845]: Emulator’s IO-socket ‘/tmp/1907362406750412530/sdlonp-iosocket-emu’ was not found.
    eaas-desktop | Nov 3 03:50:33 7d95fa9ee591 guacd[845]: Unable to connect to the emulator.
    eaas-desktop | Nov 3 03:50:33 7d95fa9ee591 guacd[845]: Connection did not succeed

  2. neelofar
    October 23, 2017 @ 5:01 am CEST

    Do we have any updated post available on adding ROMS for MacOS?

  3. klaus
    September 27, 2017 @ 8:20 am CEST

    You may have to setup / configure your local keyboard layout. Menu -> Settings

  4. thorsted
    September 26, 2017 @ 9:35 pm CEST

    I successfully installed DOS, but I can’t seem to get the shift key working on my keyboard. I can’t do a drive change without the shift key.

  5. klaus
    September 26, 2017 @ 7:50 am CEST

    The reason you see these errors, are most likely the lack of the required ROMs for your MacOS 7.

    I’ll write a short intro how to deal with ROMs with the next blog post which is on importing disk images (including MacOS) images.

Leave a Reply

Join the conversation