<commit_before># API-X development

This repository contains development and proof-of-concept code for API-X.  API-X may
be demonstrated in action by running Vagrant using the included vagrantfile.  This will
launch a VM into which several docker containers will be run, representing API-X and various
backend services (e.g. fedora itself, message routing, API-X extensions, etc)

## API-X POC/demo services
A description of API-X services can be found in [poc-services/README.md](poc-services/README.md)

## Prerequisites 

Building the code requires Maven 3.x, and Java 8.

Running API-X in Vagrant for demonstration/development purposes requires Vagrant and Virtualbox.  Linux users can avoid
installing Virtualbox if they use their own local installed Docker engine to run containers.
* [Vagrant Download](https://www.vagrantup.com/downloads.html) (tested on version 1.8.1)
* [VirtualBox Download](https://www.virtualbox.org/wiki/Downloads) (tested on version 5.0.14 for OS X hosts, amd64; _not_ the extension pack)

## Quickstart
By default, this will launch a Virtualbox VM running Ubuntu 14.04 LTS (a "docker host VM") and will run docker 
images within this VM.  Additionally, this VM will expose ports on your local machine (e.g. for viewing with a web 
browser).  This pattern works on all platforms (Linux, Mac OS, and Windows).  Linux hosts may choose to configure 
Vagrant to launch Docker on their own machine, rather than launching a separate VM.  This is discussed in a separate 
section.

### TL;DR
* `mvn install`
* `vagrant up`
* try `vagrant up` again if something fails (e.g. faileed download)

### Starting/Stopping
* By default, the Virtualbox VM creates a private network on your machine, and is accessible at the IP address 
 `10.11.8.11`.  If this poses a problem, you may edit `DockerHostVagrantFile` to change this IP, or turn it off entirely.
  If the default VM network address of `10.11.8.11` is OK, then you do not need to do anything.
    * If you wish, you may give `10.11.8.11` a human readable hostname (like `vagrant.local` or `dockerhost`) by 
      editing the hosts file on your local machine (`/etc/hosts` on unix-like systems).  
* In the project's root directory (the one containing `Vagrantfile`), run `mvn install`, then vagrant up`
	* You'll see lots of text fly by as it launches a VM, builds a docker image, and starts.  
	  This can take several minutes.  Subsequent runs will be much faster as once the docker images
	  have been built, there is no reason to re-build them unless changed (e.g. by a developer)
* Optionally, in order to share files with the VM (e.g. read log files, update configuration), you may wish to
  mount a network share provided by the VM.  This is accessible at `\\10.11.8.11\shared`.  This can
  be convenient for inspecting data files of various services.
* When you are finished, type `vagrant halt`.  Type `vagrant up` at any time to re-launch the docker images, with your
  data intact.
* Suunce docker images are built from scratch if they don't already, exist, and downloading content can always
  fail due to network effects, you may end up with one or more failed image buildds.  If this happens, just run
  `vagrant up` again.  It will attempt to build any images that have not successfully resulted in running containers

## Verification
These verification steps can be used to assure that the docker instance(s) are running and are accessible.  The
instructions assume default settings, so you will need to adjust accordingly if you, say, changed the port numbers.
Additionally, because the VM appears to your local machine as a separate networked resource, for any URL you can 
use something like `http://10.11.8.11` (or `http://dockerhost` if you gave it a name like `dockerhost` in your hosts
file) instead of `http://localhost`.

* Point your browser to [http://10.11.8.11:8080/rest](http://10.11.8.11:8808/rest).
	* You should see Fedora, with an empty root container
	* Create an object through Fedora's UI
* point your browser to Fuseki at [http://10.11.8.11:3030/fcrepo](http://10.11.8.11:3030/fuseki)
	* You should see some triples!

## Working with Vagrant and Docker
This section gives some useful commands for interacting with the api-x docker containers via Vagrant at the
command line.  Note:  the Vagrant docker provider is a little quirky, and doesn't seem to work entirely as advertised
all the time.

All Vagrant commands assume you are in the root of the fcrepo-api-x reposiory working directory.

### See the status of containers or host vm
Run `vagrant status` to just get the status of all docker containers<commit_msg>edit some text<commit_after># API-X development

This repository contains development and proof-of-concept code for API-X.  API-X may
be demonstrated in action by running Vagrant using the included vagrantfile.  This will
launch a VM into which several docker containers will be run, representing API-X and various
backend services (e.g. fedora itself, message routing, API-X extensions, etc)

## API-X POC/demo services
A description of API-X services can be found in [poc-services/README.md](poc-services/README.md)

## Prerequisites 

Building the code requires Maven 3.x, and Java 8.

Running API-X in Vagrant for demonstration/development purposes requires Vagrant and Virtualbox.  Linux users can avoid
installing Virtualbox if they use their own local installed Docker engine to run containers.
* [Vagrant Download](https://www.vagrantup.com/downloads.html) (tested on version 1.8.1)
* [VirtualBox Download](https://www.virtualbox.org/wiki/Downloads) (tested on version 5.0.14 for OS X hosts, amd64; _not_ the extension pack)

## Quickstart
By default, this will launch a Virtualbox VM running Ubuntu 14.04 LTS (a "docker host VM") and will run docker 
images within this VM.  Additionally, this VM will expose ports on your local machine (e.g. for viewing with a web 
browser).  This pattern works on all platforms (Linux, Mac OS, and Windows).  Linux hosts may choose to configure 
Vagrant to launch Docker on their own machine, rather than launching a separate VM.  This is discussed in a separate 
section.

### TL;DR
* `mvn install`
* `vagrant up`
* try `vagrant up` again if something fails (e.g. faileed download)

### Starting/Stopping
* By default, the Virtualbox VM creates a private network on your machine, and is accessible at the IP address 
 `10.11.8.11`.  If this poses a problem, you may edit `DockerHostVagrantFile` to change this IP, or turn it off entirely.
  If the default VM network address of `10.11.8.11` is OK, then you do not need to do anything.
    * If you wish, you may give `10.11.8.11` a human readable hostname (like `vagrant.local` or `dockerhost`) by 
      editing the hosts file on your local machine (`/etc/hosts` on unix-like systems).  
* In the project's root directory (the one containing `Vagrantfile`), run `mvn install`, then vagrant up`
	* You'll see lots of text fly by as it launches a VM, builds a docker image, and starts.  
	  This can take several minutes.  Subsequent runs will be much faster as once the docker images
	  have been built, there is no reason to re-build them unless changed (e.g. by a developer)
* Optionally, in order to share files with the VM (e.g. read log files, update configuration), you may wish to
  mount a network share provided by the VM.  This is accessible at `\\10.11.8.11\shared`.  This can
  be convenient for inspecting data files of various services.
* When you are finished, type `vagrant halt`.  Type `vagrant up` at any time to re-launch the docker images, with your
  data intact.
* Since docker images are built from scratch if they don't already, exist, and downloading content can always
  fail due to network effects, you may end up with one or more failed image buildds.  If this happens, just run
  `vagrant up` again.  It will attempt to build any images that have not successfully resulted in running containers

## Verification
These verification steps can be used to assure that the docker instance(s) are running and are accessible.  The
instructions assume default settings, so you will need to adjust accordingly if you, say, changed the port numbers.
Additionally, because the VM appears to your local machine as a separate networked resource, for any URL you can 
use something like `http://10.11.8.11` (or `http://dockerhost` if you gave it a name like `dockerhost` in your hosts
file) instead of `http://localhost`.

* Point your browser to [http://10.11.8.11:8080/rest](http://10.11.8.11:8080/rest).
	* You should see Fedora, with an empty root container
	* Create an object through Fedora's UI
* point your browser to Fuseki at [http://10.11.8.11:3030/fcrepo](http://10.11.8.11:3030/fcrepo)
	* You should see some triples!

## Working with Vagrant and Docker
This section gives some useful commands for interacting with the api-x docker containers via Vagrant at the
command line.  Note:  the Vagrant docker provider is a little quirky, and doesn't seem to work entirely as advertised
all the time.

All Vagrant commands assume you are in the root of the fcrepo-api-x reposiory working directory.

### See the status of containers or host vm
Run `vagrant status` to just get the status of all docker containers
{'fraction_non_alphanumeric': 0.07064160725858717, 'fraction_numerical': 0.020306761719593863, 'mean_word_length': 4.067870826491516, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 18, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2287374', 'n_tokens_mistral': 2749, 'n_tokens_neox': 2554, 'n_words': 1359}