linagora-rse/docker/doc/run.md

Linagora RSE

# Howto use ESN with Docker

The RSE can be used with Docker to ease the deployment of all the required components:

- Redis
- RabbitMQ
- MongoDB
- Apache Cassandra
- Apache James
- Elastic Search
- Sabre DAV
- OpenPaaS ESN

Note: All the docker related instructions below has been tested with docker-compose 1.6.0 and docker 1.10.0.
Please check [docker.com](http://docker.com) for installation instructions.

## Howto Launch OpenPaaS

### With docker-compose

docker-compose is the simplest way to run a distributed application, so you can launch the OpenPaaS platform in a single command.

There are two ways to run the OpenPaaS platform with docker-compose:

1. Build required containers yourself from sources.
2. Run from Docker Hub containers which are available from https://hub.docker.com/u/linagora/

**Build required containers yourself from sources**

The default docker-compose descriptor can be found at the root or the current repository (check the docker-compose.yml file).

You have to build the ESN container before to launch OpenPaaS. Go to the top repository folder then:

```
docker-compose -f ./docker/dockerfiles/platform/docker-compose.yml build
```

Note: If your have an error saying that the linagora/esn-base can not be found, you have to build it before. Refer to the 'dev' section below in this case.

Then you can run:

``` sh
PROVISION=true DOCKER_IP=<YOUR_DOCKER_IP> ESN_PATH=$PWD docker-compose -f ./docker/dockerfiles/platform/docker-compose.yml up
```

**Run from Docker Hub containers (ie build nothing)**

```bash
PROVISION=true DOCKER_IP=<YOUR_DOCKER_IP> ESN_PATH=$PWD docker-compose -f ./docker/dockerfiles/platform/docker-compose-images.yml up
```

In both cases, environment variables are defined like:

- PROVISION (Required on first launch only): Tell OpenPaaS to initialize configuration and provision some users/domains/communities so that once launched, you can log in into OpenPaaS.
- DOCKER_IP: Must be the docker-machine IP (default machine is accessible at 192.168.99.100 on OS X and Windows, 172.17.0.1 on Linux, type 'docker-machine ip default' to check the value). It is required to set this IP so that the configuration is generated from the right value. If not set, the webserver may not provide some assets correctly.
- ESN_PATH: Should always be the absolute path of your ESN sources. This variable is used to interpolate some paths in the docker-compose file.

Launching the platform may take some time (1-2 minutes), grab a coffee and be ready for the next steps!

The open-paas.org domain is created by default for testing, but you can also create your own domain.

- Add a Domain:

```bash
docker exec esn_james java -jar /root/james-cli.jar -h localhost adddomain my-custom-domain.org
```

You may want to create some users in the newly created domain.
Note that OpenPaaS users and their mailboxes are automatically provisioned on first login from the OpenPaaS application.
So you do not need to create any user to use OpenPaaS, but you can check that all is working with the following commands:

- To create an user:

```bash
docker exec esn_james java -jar /root/james-cli.jar -h localhost adduser me@open-paas.org secret
```

To check that the user is well created, you can telnet on the James IMAP port:

```
telnet <YOUR_DOCKER_IP> 1143
```

and login with:

```
A0 LOGIN me@open-paas.org secret
```

The server should print some logs in the docker-compose console and send you back a login completed message:

```
A0 OK LOGIN completed.
```

Provisioned users have a random generated password. If for some cases, you want to configure and use an external mail application (like in [./mailer.md](./mailer.md)), you can update the user password like this:

```
# Change the admin@open-paas.org password to 'secret'
docker exec esn_james java -jar /root/james-cli.jar -h localhost setpassword admin@open-paas.org secret
```

**We are now ready!** You should now be able to use several services (check the docker-compose.yml file to find the list or exposed ports).
Let's connect to the OpenPaaS Web appliction on http://<YOUR_DOCKER_IP>:8080. If you launched docker-compose with the PROVISION variable set to true, you can log in with

```
username: admin@open-paas.org
password: secret
```

You can check the [./mailer.md](./mailer.md) documentation to look how to configure a Mail client to access to the OpenPaaS mail server.


### Without docker-compose

If you have only docker installed on your machine, you can avoid to install docker-compose by running it as a container.

In such context, the ESN containers creation command becomes:

```
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/compose  -e PROVISION=true -e DOCKER_IP=<YOUR_DOCKER_IP> -e ESN_PATH=$PWD -w /compose -ti docker/compose:1.6.2 -f docker/dockerfiles/platform/docker-compose.yml up
```

and the containers removal command is:

```
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/compose  -w /compose -ti docker/compose:1.6.2 -f docker/dockerfiles/platform/docker-compose.yml down
```

# Dev

All the OpenPaaS Dockerfiles and docker-compose descriptor heavily use environment variables to create required resources such as configuration files, endpoints, etc...
This allows us to easily configure them when containers are launched, will it be from docker, docker-compose or any other high level abstraction.