Public Repository

Last pushed: 7 months ago
Short Description
A web application for the digital study of patterns in visual communication.
Full Description

What is Archetype?

Archetype (formerly known as 'The DigiPal Framework') is an open-source web application for the online presentation of images with structured annotations and data which allows users to search for, view, and organise detailed characteristics of handwriting or other material in both verbal and visual form. Designed primarily for the palaeographical analysis of handwriting, it was first developed for the Digital Resource and Database for Palaeography, Manuscript Studies and Diplomatic (DigiPal) project, funded by the European Research Council.

More info soon on Archetype.ink

What is Archetype for Docker?

This web page describes a version of Archetype that runs on Docker. It can be used for the following goals:

  • To try out a demonstration instance of Archetype to evaluate it or understand how it works
  • To start using Archetype on your laptop for your own personal research with your own material

Although Archetype can be (and has been) deployed by King's Digital Lab on production sites, the current Docker version of Archetype is not presently suitable for a production environment. Please go to archetype.ink to get in touch with us if you need more than a local (i.e. laptop-bound) instance of Archetype.

This version of the Archetype framework is made available via a system called Docker. Docker allows us to ship the same software to any type of computer. Fortunately, you don't need to know much about Docker except from a couple of bits of jargon:

  • A Docker Image is a particular version of a software that you have downloaded and can be installed on your machine. It is not to be confused with a visual image like a photo. You might compare it to a Microsoft Office DVD you have bought from a shop.
  • A Docker Container is the result of installing the Image. It is an instance of an Image (e.g. Archetype version 2.1.0) that you can run on your laptop. You can compare it with Microsoft Office you've installed on your computer from the DVD.
  • A Docker Volume is the folder on your machine where a Container stores its data. You can compare that to you Documents folder where you save your Word files.
  • Kitematic: is similar to an App Store. It is a desktop application that lets you search for Docker Images, download them and create Docker Containers from them.

The key principle of Docker distribution of Archetype is that once a new version of Archetype Image is available you can remove the Docker Container, download the new Image from internet and then install it. All your data will be preserved in the same Docker Volume. The upgrade process is explained in more details further down.

Requirements

You will need:

  • an internet connection
  • Mac must be a 2010 or newer model with OS X El Capitan 10.11 and newer macOS
  • OR 64 bit Linux with kernel > 3.10 and
  • at least 4GB of RAM

Please note that Docker does NOT fully support Windows at this time. Archetype works on Windows but with the following limitation: your data will remain within the Docker Container. So it is not fit for anything other than trying out the demonstration site. We will continue to increase support for Windows in the future.

How to install Docker and Kitematic?

On a Mac

Go to Docker for Mac. On that web page click the blue button "Get Docker" or "Get Docker CE for Mac (Stable)" and read the instructions on how to install it.

Install Kitematic. On that web page, click the version of Kitematic that matches your operating system (Mac, Ubuntu or Windows) to download it. Once downloaded click the filename in your browser to start the installation of Kitematic.

On Windows 7, 8 or 10 Home

On Windows 7, 8 or 10 Home edition, you'll need to install Docker Toolbox. On that web page click the big button labelled 'Get Docker Toolbox for for Windows" then, once the download is complete, click the file to start the installation.

Note that 32-bit versions of Windows are not supported.

On Windows 10 Pro

Go to Docker for Windows. On that web page click the blue button "Get Docker" or "Get Docker CE for Windows (Stable)" and read the instructions on how to install it.

Install Kitematic. On that web page, click the version of Kitematic that matches your operating system (Mac, Ubuntu or Windows) to download it. Once downloaded click the filename in your browser to start the installation of Kitematic.

On Ubuntu

Install Docker for Ubuntu

Install Kitematic. On that web page, click the version of Kitematic that matches your operating system (Mac, Ubuntu or Windows) to download it. Once downloaded click the filename in your browser to start the installation of Kitematic.

How do I start Docker and Kitematic?

Step 1 (Mac or Windows 10 Pro only): Start Docker

On a Mac or Windows Pro you must first start Docker. Find Docker in you application list and start it. You should see a little whale icon in your task bar. Wait until the animation on the icon has stopped which indicates that Docker is ready and running. To verify this click the whale and check that it says: 'Running'.

Step 2 (any operating system): Start Kitematic

Start Kitematic. Search for Kitematic in your application list. If you don't find it, click the whale icon in your task bar (if any) to open a pop-up menu and click Kitematic in that menu.

The first time you run Kitematic on Windows 10 Home (or WIndows 7 or 8), you may see an error message. Click the 'Use Virtual Box' button. If that fails click reset then 'Use Virtual Box' button. If it still fails, then you can contact us for help.

If you see a slog-in screen asking you to "Connect to Docker Hub", just click 'Skip for Now' button in the bottom right corner.

How do I install Archetype for Docker?

Step 1: Download and start Archetype

Make sure Docker and Kitematic are started (see section above). In Kitematic click 'Docker CLI' button in the bottom left corner of the window. A terminal window will pop up. Copy and paste one of the following commands into the terminal window:

On Windows:

docker stop archetype; docker rm archetype; docker pull kingsdigitallab/archetype:latest; docker run -d --name archetype -p 9080:80 kingsdigitallab/archetype:latest; echo "INSTALLED";

On other operating systems:

docker stop archetype; docker rm archetype; docker pull kingsdigitallab/archetype:latest; docker run -d --name archetype -v ~/Documents/Kitematic/archetype/home/digipal/digipal_project:/home/digipal/digipal_project:cached -p 9080:80 kingsdigitallab/archetype:latest; echo "INSTALLED";

Press the Enter/Return key to run the command.

Step 2: wait...

Then be patient! This command will download the latest Archetype Image and create a Container for you. Wait until you see the word 'INSTALLED' then close the Terminal window and return to Kitematic.

Now close Kitematic and start it again.

Step 3: View your Archetype site!

In Kitematic you'll see your Archetype Container listed on the left hand side. Click it to select it (Archetype will be highlighted in blue). In the centre you should see a black box. As the Container starts running, a lot of information will be logged there. You don't need to understand the messages or take note of them, but simply wait for a minute or so until you see the message 'Website is Running'. Find the words 'Web Preview' on the right hand side of Kitematic window. Click the icon next to it (the one with an arrow coming out of a square) to preview the site in your browser.

Very quick tour

This is a very quick and partial tour of some of the key features of framework. Don't worry if you get lost as more documentation is available on Archetype Github Space and detailed editorial guides will be produced at a later stage.

You can now try Archetype demonstration site in your preferred browser. Click Search in the main menu to see one annotated image of a manuscript. You can click the image thumbnail to jump to the annotator page and see it in full resolution with all the separate annotations. On that web page click the 'Texts' tab, then click 'transcription' to see the image and the text in the Text Viewer.

Return to the home page and click the 'Log in' link in the bottom of the page. The username is 'admin' and the password is 'admin'. Once you are logged in you can edit all the content. You may want to first try creating annotations.

Find the manuscript image from the search page again and click the thumbnail to go to the high resolution web page. You can use the tool bar on the left to draw and save new annotations and see their cutouts under the 'annotations' tab.

When you are logged in you can use the Text Viewer (described above) to edit your transcriptions, translations or other texts related to a physical document. From the search page, click 'Texts' in the left hand side to list all the text. Then click 'view' to see that text in the Text Viewer. Now move your mouse over the text pane to see the full toolbar and click the icon that looks like a pencil. That button switched the pane to edit mode where you can edit the text and apply some simple markup. When finished, click the pencil button again to leave the editing mode.

The entire database can be edited with web forms in the backend interface (also called 'admin interface' or 'mezzanine'). Click the 'Database' link in the footer to go to the Database Dashboard. While it lists all the tables in the DB, thankfully only a handful of them are really essential for the most frequent needs. Feel free to click around to get an idea of how the system works. You could start with the Image table.

How do I stop and restart Archetype?

Back to Kitematic; make sure the 'Archetype' container is selected on the left hand side (click Container then Archetype if not). In the top part of the Kitematic window, in the centre you should see a 'Stop' and a 'Start' button to respectively quit and restart the application.

Note that if you are using a Mac or Windows Pro you always need to make sure Docker is started before you start Kitematic.

Using Archetype for your own research

The demo site contains only a sample manuscript image. If you are on Ubuntu or on a Mac you can use this site as a starting point for the analysis of your own research material. Your data should be safe and can be ported to future versions of Archetype.

You can access your Archetype data folder from Kitematic. In Kitematic start Archetype then on the right hand side, under 'Volumes', click the blue folder icon. This will open the your data folder. It contains all your customisations, database, image files and image gallery / web assets. All files can be modified from your host computer apart from the database. If you need the database (e.g. making a backup), you must completely stop Archetype first to avoid any data corruption.

Customising your site

The framework is quite generic and can be adapted to different needs and different types of material. Many things can be customised or extended, such as the search page, the mark-up for your text, the terminology used to describe the letter-forms or other regions of the images, the look and feel of the site, the layout and presentation of the web pages etc...
(We are planning to document the customisations on a separate site.)

The important thing to remember is that all changes should be confined to the digipal_project folder. Any patch applied to the code in other folders or the database will almost certainly make your site impossible to upgrade with Docker and it won't benefit from future enhancements or bug fixes. If you have Python developers in your team you can consider forking the GitHub repository and working on changes that are likely to become part of the main code base.

Upgrading Archetype

Note: only for Mac and Ubuntu.

From version 2.0.0 and above

A bold green message on the dashboard will appear in the backend interface (http:/...:9080/admin) when a new release of Archetype becomes available. Before you upgrade make a backup of your data (see backup section just below).

To upgrade your Archetype Image and Container, go to Kitematic, click the 'DOCKER CLI' button in the bottom left corner to open a new terminal window. From there copy and paste the following line:

docker stop archetype; docker rm archetype; docker pull kingsdigitallab/archetype:latest; docker run -d --name archetype -v ~/Documents/Kitematic/archetype/home/digipal/digipal_project:/home/digipal/digipal_project:cached -p 9080:80 kingsdigitallab/archetype:latest; echo "INSTALLED";

Press enter/return key to run the command.

Be patient, this will download the latest Archetype Image and create a Container for you. Wait until you see the word 'INSTALLED' then close the Terminal window and return to Kitematic.

In Kitematic you'll see your Archetype container listed on the left hand side. Click it to select it (Archetype will be highlighted in blue). In the centre you should see a black box. As the container starts running, a lot of information will be logged there. You don't need to understand them. Just wait for a minute or so until you see 'Website is Running'. Find the words 'Web Preview' on the right hand side of Kitematic window. Click the icon next to it (the one with an arrow coming out of a square) to preview the site in your browser.

From version 1.2.2+

If your Archetype site is between version 1.2.2 and version 2.0 the upgrade procedure is slightly different:

  1. Make sure you have an internet connection
  2. Start Archetype (from Kitematic)
  3. From Kitematic, go to the terminal (click 'Exec' button)
  4. Type 'apt-get install -y wget' (without quotes) then press enter
  5. Type 'wget -qO zip_digipal_project.py http://bit.ly/2xERjk7 && python zip_digipal_project.py'
  6. Go to your site home page
  7. Add this to the URL in the browser address bar: '/static/archetype.tar.gz'
  8. The browser should download archetype.tar.gz
  9. Upgrade Archetype (see all the instructions in the section '2.0.0 and above')
  10. Stop Archetype from Kitematic (make sure you have first verified the site is running from your browser)
  11. Remove all the content inside your data folder
  12. Copy archetype.tar.gz inside that folder
  13. Start Archetype again

Now your old content should work on the latest version of Archetype.

From versions prior to 1.2.2

There is not yet an upgrade plan for sites created with DigiPal v1.0. ;(

Which version of the framework am I using?

Start Archetype, visit the site home page. Click the Admin/Database link in the footer of the web page. In the admin dashboard you should see a version number.

If not, you are using an old version and you can try this instead. Go to your site home page and use your browser 'View Page Source' function. You should see something like this in the first 20 lines of HTML:

`<!-- DigiPal - build number 0 - build date - 1.2.2b () -->

This means that 1.2.2b is the version of Archetype

Backing up your data

There are two ways to save your data:

  1. Stop the app then copy your data folder to another location on your hard drive or other storage device.
  2. Start your app, click 'Exec' button in Kitematic to open a Terminal window. Inside that new window, you just have to type 'python build/zip_digipal_project.py' (without the quote then press enter/return). Once that's done, type 'exit' to leave the Terminal window. Now go to your browser, visit the home page of your site, then add this to the address/URL '/static/archetype.tar.gz' and press enter. Your browser should download a file. Move that file to a safe location (USB key or external hard-drive).

The second method is more cumbersome but the backup is more compact and portable.

Sharing your Archetype site and data on the web

Archetype was conceived especially to let researchers publish and share their data and evidences with others via the web. Many public websites based on Archetype have been set up for this purpose as part of larger research projects. Please note that making your site public requires some additional technical work as it is crucial that the site is made secure and production ready. By default the current version of Archetype for Docker is for personal use only, it is NOT SAFE FOR PRODUCTION ENVIRONMENTS. We are planning to provide more detailed instructions on how to deploy Archetype on a production server; in the meantime you are welcome to contact the development team at King's College London if you need assistance or a quote.

Other ways to install Archetype

Pulling Image from Dockerhub

For people who are familiar with Docker:

*docker run -d --name archetype -v ~/Documents/Kitematic/archetype/home/digipal/digipal_project:/home/digipal/digipal_project:cached -p 9080:80 kingsdigitallab/archetype:latest

Building with the Dockerfile

See /build/Dockerfile on github.

Using DockerToolbox or Boot2Docker

We no longer recommend using DockerToolbox, Boot2docker or docker-machine because they are more limited than Docker for WIndows, Docker for Mac or Native docker for ubuntu.

Building from Github

If you are a software developer or system administrator it is entirely possible to install Archetype from scratch by cloning the repo from Github and borrowing some setup code snippets from build/Dockerfile to learn how to install all the dependencies. This approach is demanding and time consuming but it gives you full control over the deployment on a production server or on a development environment. Archetype is open source, feel free to fork on Github and contribute.

Issues, questions and requests?

Please use the Archetype Issue tracker on Github

References

Archetype site: http://archetype.ink (coming soon!)
Archetype on Github: https://github.com/kcl-ddh/digipal
DigiPal project website: http://www.digipal.eu/
Department of Digital Humanities, King's College London: https://www.kcl.ac.uk/artshums/depts/ddh/index.aspx
King's Digital Lab, King's College London: https://www.kdl.kcl.ac.uk/

Geoffroy Noël (Research Developer, King's Digital Lab)

Docker Pull Command
Owner
kingsdigitallab