The Ark's source code and documentation is hosted by GitHub at this location. To check out the repository using Git, issue the following command:

git clone https://github.com/The-Ark-Informatics/ark.git TheArk

 

The source code can be modified and redistributed under the terms of the GNU GPL v3 license.

The Ark is built upon open source libraries and frameworks including Apache Wicket and Shiro, Spring and Hibernate. Pedigree visualisation is provided by integration with Madeline.

To become a member of the developer team and contribute to the project, please email This email address is being protected from spambots. You need JavaScript enabled to view it. or This email address is being protected from spambots. You need JavaScript enabled to view it..

Vagrant is a tool that allows easily configurable, reproducible and portable development environments. It uses configuration files to manage a Virtual Machine (VM), and integrates with tools such as Puppet  or Ansible to provision the VM. We have used Vagrant and Puppet to create a VM on an Ubuntu 14.04 LTS base image, with Tomcat7, SLAPD and MySQL configured to create a ready-to-go Ark server.

These instructions have been tested on OSX, and Ubuntu Linux. Windows hosts are untested.

Before attempting to using vagrant-ark, you should be comfortable with the following topics:

  • Using a command prompt
  • Virtual Machines and Virtualization
  • Version Control Systems, specifically git

The vagrant-ark repository contains a submodule of The Ark Github repository (https://github.com/The-Ark-Informatics/ark), and is pulled down with git clone --recursive. If you didn’t clone using the recursive flag, you will need to run git submodule update --init --recursive to pull The Ark repository.

Prerequisite Software

Setup

Recursively clone the vagrant-ark repository:

 git clone --recursive https://github.com/The-Ark-Informatics/vagrant-ark.git

 

Navigate into the vagrant-ark directory, then run the Virtual Machine:

      cd vagrant-ark
      vagrant up

 

The first time vagrant up is run, Vagrant will automatically provision the VM, installing and configuring all dependencies needed to run The Ark.  

Usage

Once the VM is running, you can SSH into it via the vagrant ssh command from within the project directory. To access The Ark, navigate to http://192.168.33.10:8080/ark in your browser.

For development use, there are two approaches to working with vagrant-ark.

  1. You can work directly on the code in the submodule, or
  2. You can work on a copy of The Ark outside of vagrant-ark and copy the compiled WAR into the shared webapps directory.

For approach 1, the code in src/ark will be recompiled and deployed if the image is provisioned again (i.e with vagrant up --provision), however database changes will persist throughout provisions.

With approach 2, Tomcat will automatically detect when the WAR file in the shared webapps directory has been modified, and will automatically redeploy it.

You should note that new or modified database patches will not be applied using either of the methods above, and should be managed independently.

Users and Passwords

The username and passwords for the services configured in vagrant-ark are listed below.

Service Account/Username Password
The Ark This email address is being protected from spambots. You need JavaScript enabled to view it. password
Linux User vagrant vagrant
Slapd cn=admin,dc=the-ark,dc=org,dc=au password
MySQL root password

 

The Docker configuration supplied in The Ark repository allows quick and easy building of the system. This configuration has four containers defined; MySQL, LDAP (Slapd), Tomcat and Maven. The containers are integrated using Docker Compose.

Note: at present, this process has only been tested and verified to work on Ubuntu 14.04LTS. We are working towards ensuring compatibility with other operating systems such as Microsoft Windows and Apple OSX.

Prerequistite software

Microsoft Windows and Apple OSX users should download "Docker for Windows" and "Docker for

Usage

Assuming the source code repository has been checked out using Git and that the Docker platform is running:

  1. cd docker/
  2. docker-compose build
  3. docker-compose up

Extra Commands

Command Usage
docker-compose up -d Starts the containers in daemon mode meaning that no logs are printed to STDOUT.
docker-compose down -v Tears down all containers, and deletes all of the associated storage volumes.
docker exec -it <containername> /bin/bash Starts an interactive bash session within the container named <containername>.

Passwords

The default passwords are contained in docker/env_file and should be modified before the initial docker-compose up command, as the services are configured in the first run of each container. Passwords can be changed by tearing down all containers and deleting their volumes, however this will also delete any data stored in the MySQL and LDAP containers.

Configuration

Inside docker/env_file, the following Environment Variables can be set to configure the software inside each container:

Environment Variable Usage Default Value
MYSQL_ROOT_PASSWORD Changes the MySQL root user password mysql-password
SLAPD_PASSWORD The password for the LDAP database slapd-password
ARK_USERNAME The Ark Superuser's username This email address is being protected from spambots. You need JavaScript enabled to view it.
ARK_SUPERUSER_PASSWORD The Ark Superuser's password Password_1

Explanation

When docker-compose up is called for the first time, all four containers are built and started. The Maven and MySQL containers begin their work, compiling the web application and importing the base database respectively, while the Tomcat and LDAP containers wait for the output of Maven. The LDAP container waits until the ark-user-account Jar has been created, as it is needed to populate the LDAP database with The Ark root account, and the Tomcat service waits until ark.war has been created, before deploying it.

Usage

With "docker-compose build" and "docker-compose up" complete, The Ark will be accessible via http://localhost:8080/ark in your browser. The SLAPD (LDAP) and MySQL (database) services are also available at localhost:389 and localhost:3306 respectively.

Container-specific Quirks

For the maven container, we mount ~/.m2 to /root/.m2 so that all maven repositories are cached and the user's maven settings.xml file applies.