Running Archetype with Kitematic

This page is now obsolete. It is kept here for people with older systems, but it is recommended that you install Archetype on your local machine using Docker for Mac or Docker for Windows rather than Docker Toolbox as described here. See Installing and Running Archetype.

Deprecated instructions

The DigiPal framework is a generic system which can be installed and run from your own computer. This will produce an 'empty' version of the framework to which you can then add your own content. If you do this then your version of DigiPal will be for your own private use only; it will not be available on the internet or visible to anyone else.

The recommended way to install DigiPal is using Docker. Docker itself is relatively unfriendly to use, but if you are running Windows or MacOS then you can use Kitematic which provides a graphical interface to Docker and is generally easier to run. The instructions for this graphical procedure are given here; if you want to use Docker directly then see DigiPal Docker page.

Warning: To create and run a new instance of DigiPal on your computer, you will need to download and install approximately 1 GB of files. Please ensure that you have enough hard disk space, as well as a good internet connection.

Installing and Setting Up DigiPal for the first time

The procedure to install and set up DigiPal takes a bit of time but should only need to be done once.

1. Download and install the Docker Toolbox (approx. 120 MB). This includes the Kitematic software which is available for Windows and MacOS.
2. Run Kitematic. This will start the Docker Virtual Machine which can take a while, depending on your machine. Be patient.
3. Type 'DigiPal' into the box labelled 'Search for Docker Images from Docker Hub'. Kitematic should then find and show gnoelddh/digipal.
4. Click on 'Create'. This will download the DigiPal image (approx. 800 MB).
5. Kitematic will automatically start a new instance of the DigiPal server, but will do so with the wrong port mappings. To fix this do the following:
   1. Stop the running container by clicking on 'Stop' in Kitematic
   2. Open the Docker CLI (Command Line Interpreter), by clicking on the icon in the bottom left corner of the Kitematic window
   3. Copy and paste the following into the window: docker run -t -i -p 8080:8080 -p 8081:8081 -p 2222:22 gnoelddh/digipal. You should now see a new container (it will probably have some strange name). You should only ever use this new container with the strange name: do not use the old one called 'DigiPal'.

You should now have DigiPal running on your computer. To access it, click on 'View In Browser' using Kitematic: this should open your web browser showing an empty version of the DigiPal front page which you can then start to fill (see the 'Entering New Content' pages in this wiki). However, you will not yet be able to view or use images. To fix this, an additional step is required. This only needs to be done once, and we will ensure that this step will not be necessary in future versions of the framework.

In summary, there is one line in a settings file which needs to be changed. Because of the way the setup works, you cannot easily use a conventional text editor to make the change. Instead you need to use a very old and not user-friendly (but very reliable) editor called vi.

1. Start the DigiPal server in Kitematic, if necesary.

2. Copy or make a note of the URL. Do not include the 'http://', and do not the colon or any numbers after it (e.g. ':8080'). The part that you copy should be an IP address, that is, it should consist of four numbers separated by '.' (e.g. '192.168.90.100')

3. Click on 'Exec' in Kitematic. This will open a new terminal window.

4. Type exactly the following into the window. Do not type any other key, even 'Return', unless specified. Be careful not to mis-type the commands, either: in some systems the backspace and delete keys do not work, and even small errors can have dramatic effects. However, the text in [square brackets and italics] are descriptions to help you so you should not type these.

   cd digipal<Return>

   vi local_settings.py<Return>

   [This command should open the local_settings.py file in your window, so you should now see the contents of the file.]

   /IMAGE_SERVER_HOST<Return>

   [Your cursor should now be at the start of a line which reads IMAGE_SERVER_HOST = 'localhost:8081'. We will now change that line.]

   wwwdwi [Do NOT press at this point!]

   [Each time you press 'w' you should see the cursor jump forward until it is at the start of the word 'localhost'. Pressing 'dw' should then delete the word 'localhost'. When you press 'i', nothing should appear to happen except that the word 'INSERT' will (probably) appear at the bottom of your window. This means that we are now in 'Insert' mode and you can type in new text.]

   <Type or paste in the IP address from Step 2 above, then press ESC>

   [You should now see a line of text something like IMAGE_SERVER_HOST = '192.168.90.100:8081', where the number before the colon is your address from Step 2 above. After you press , the word 'INSERT' should no longer be visible.]

   :wq<Return>

   [This should now save your changes and bring you back to the command line]

   <Ctrl-D>

   [This should now exit the terminal (your window will probably still be visible but you will probably see a different cursor, or perhaps cannot type anything at all).]

5. Now Quit the Terminal application

6. In Kitematic, restart the container

You should now have a functioning version of the DigiPal instance.

Note that you must leave Kitematic running while you are using DigiPal: if you quit Kitematic then your DigiPal instance will stop working as well.

Running DigiPal

Once you have successfully installed DigiPal then to restart it do the following:

1. Launch Kitematic
2. Select the container (in the left-hand bar of the Kitematic interface)
3. Click on 'Start', and wait until Kitematic says 'Running'
4. Open the URL in your browser

Shutting Down DigiPal

If you want to stop the DigiPal server, then do the following:

1. In Kitematic, if necessary then select the container in the left of the window
2. Click on Stop and wait until Kitematic says 'Stopped'
3. Quit Kitematic

Running Multiple Instances of DigiPal

If you wish then you can run more than one separate instance of DigiPal on your computer, perhaps for different projects or to experiment with different things. Assuming that you already have DigiPal running on your computer, you can repeat the procedure given above under 'Setting up and Installing DigiPal', starting from Step 2, and if necessary then 'Fixing the Image Server' as well. This will create new containers which you can start and stop using Kitematic as described above.

What Next?

In order to start adding new content, you will need to log in to The Admin Interface. To do this, the login and password are admin and admin. You must change these immediately to something more secure (for which see further Changing or Resetting Passwords). You can then start to add new content, for which see Adding Items (Manuscripts), Adding Images, and so on.

Advanced: If you want to do more advanced changes to the framework then you can access the server by clicking on the Exec icon in Kitematic. This will then give you access to the Django framework where you can edit the python code directly. If you expect to do this often then you will probably want to change the default shell (from sh); to do this, with your container running, in Kitematic go to the 'Settings' tab, then the 'General' tab, where you can add a new environment variable (e.g. with a key of 'SHELL' and a value of '/bin/bash'). See further Adding Environment Variables in the Kitematic User Guide.