|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.
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.
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:
The first time vagrant up is run, Vagrant will automatically provision the VM, installing and configuring all dependencies needed to run The Ark.
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.
- You can work directly on the code in the submodule, or
- 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.
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.
Microsoft Windows and Apple OSX users should download "Docker for Windows" and "Docker for
Assuming the source code repository has been checked out using Git and that the Docker platform is running:
- cd docker/
- docker-compose build
- docker-compose up
|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>.|
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.
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_SUPERUSER_PASSWORD||The Ark Superuser's password||Password_1|
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.
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.
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.