modules/containers.mdtext

Title: Aries Containers

# Aries Containers
Aries Containers is a project to manage container deployment, such as docker containers, from a Java API.

Many technologies exist to manage container deployments. Examples include Kubernetes, Marathon/Mesos, Docker Swarm, Amazon ECS 
and others. While each technology provides specific features, many of these management technologies share common behaviour.
Aries Containers provides an abstraction that allows users to easily switch between these technologies. 

Benefits:

  - Requirements change - container users may find that they need to change target platforms at short notice. Using an abstraction API 
helps making such changes without too much additional work.
  - Testing - many container management systems require cluster of machines or otherwise large setup which may make testing during
development difficult. Aries Containers also contains a `docker.local` binding which makes it possible to run the same code with a different 
binding on a local developer machine, as long as docker is installed there.

Current modules:

  - `containers-api` - the API implemented by the various bindings.
  - `containers-docker-local` - Binding that uses the local docker installation.
  - `containers-marathon` - Marathon binding.
  - `containers-parent` - Parent pom.
  - `containers-examples` - Examples.
  - ...

This project may be used as input to the design process of the [OSGi RFP 179][1].

# Source
The Aries RSA source is in a separate [git repository aries-containers][2] there is also a [mirror on github][3].

To build the source, just run:

`mvn install`

Java 1.8 or higher is required. Maven 3.3.9+ is recommended.
# Quick Start
TODO

#Bindings

##Docker Local

This binding works by issuing `docker` commands on the local machine and is very useful for testing. Make sure the environment 
variables normally provided via `docker-machine env <myenv>` are set.

OSGi ServiceManager identifier: `container.factory.binding = docker.local`

Constructor, for use outside of OSGi: `org.apache.aries.containers.docker.local.impl.LocalDockerServiceManager`

##Marathon

This binding uses Marathon as the underlying container manager. It requires the following configuration to be set:

    service.pid: org.apache.aries.containers.marathon
      marathon.url=<the URL where marathon can be contacted>

Once configured, the Marathon binding will register its OSGi service. 
OSGi ServiceManager identifier: `container.factory.binding = marathon`

Constructors, for use outside of OSGi: `org.apache.aries.containers.marathon.impl.MarathonServiceManager`

    /**
     * Create the Marathon Service Manager.
     *
     * @param marathonURL The Marathon URL
     */
    public MarathonServiceManager(String marathonURL);

    /**
     * Create the Marathon Service Manager for use with DC/OS.
     *
     * @param marathonURL The Marathon URL.
     * @param dcosUser The DCOS user or service-user.
     * @param passToken The password or token to use.
     * @param serviceAcct `true` if this is a service account `false` if this is a plain user.
     */
    public MarathonServiceManager(String marathonURL, String dcosUser, String passToken, boolean serviceAcct);


  [1]: https://github.com/osgi/design/blob/master/rfps/rfp-0179-ComputeManagementService.pdf
  [2]: https://git-wip-us.apache.org/repos/asf/aries-containers.git
  [3]: https://github.com/apache/aries-containers