A web application for the digital study of patterns in visual communication.
2.9K
If you are using Windows, please read the important warning in the Requirements section below If your project/research data is important and you want to make sure it is backed up and safe, please read the "Using Archetype for your own research" section.
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 on Archetype.ink
This web page describes a version of Archetype that runs on Docker. It can be used for the following goals:
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:
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 detail further down.
You will need:
If you are using Archetype for you own research and the data it contains becomes important to you, please do make regular backups. See the Backup section lower down this page. Backups are even more crucial on Windows. More about that below.
Short answer: yes, Archetype will work on Windows but we do not recommend it for anything beyond testing the framework or quick prototyping. Please read the following notes if you are using Windows.
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. If Docker compatibility with Windows improves that will allow us to increase our support for Windows. Windows 10 Pro and Education have better support because they use Microsoft Hyper-V for virtualisation, which in theory allows the data to stay outside the container. However, in practice this won't work because the database (postresql) requires special features not yet supported by Docker for Windows (https://github.com/docker/for-win/issues/39, https://github.com/docker/for-win/issues/445).
For Windows 10, please make sure you do not share your volume otherwise the site will become unusable and your data may be lost.
Also note that you must have virtualisation enabled to use Docker. Instructions to check if your machine has this, and how to fix it if not, are available at https://www.trishtech.com/2017/08/check-if-virtualization-is-enabled-in-windows-10/
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 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.
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. (Note you might need to log in / create an account to see 'Get Docker' link).
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.
If it is a zip file, just unzip it in a new empty folder, within the folder you'll find a Kitematic executable.
During Kitematic installation and first run, always chose Hyper-V instead of VirtualBox.
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 a Mac or Windows Pro Docker must be running before you can do anything. 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'.
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.
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";
Press the Enter/Return key to run the command.
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.
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.
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.
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.
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.
Warning: please do not use Windows for anything else than experimenting with Archetype. See the Requirement section for more information. The information below is for Mac, Linux and, possibly, Windows 10 Pro only.
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.
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.
Only for Mac and Ubuntu.
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.
If your Archetype site is between version 1.2.2 and version 2.0 the upgrade procedure is slightly different:
Now your old content should work on the latest version of Archetype.
There is not yet an upgrade plan for sites created with DigiPal v1.0. ;(
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
There are two ways to save your data:
python build/zip_digipal_project.py (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.
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.
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
See /build/Dockerfile on github.
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.
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.
Please use the Archetype Issue tracker on Github
Archetype site: http://archetype.ink 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)
Content type
Image
Digest
Size
724.8 MB
Last updated
over 4 years ago
docker pull kingsdigitallab/archetype