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.
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:
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.
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.
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.isofile 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
- 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)
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.
By klaus, posted in klaus's Blog