Merge branch 'develop'

README.md

@@ -1,34 +1,92 @@
-# orca-docker
-Packaging project for NCLS Development's [Orca](https://www.orca-solution.com/) solution.
+# orca-deploy
 
-## How to use
+Packager project for NCLS Development's [Orca](https://www.orca-solution.com/) solution.
 
-- Build and publish a [Docker](https://www.docker.com/) image of the Web server using the instructions found under `docker-compose`.
-- Bundle and deploy the [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) application with AWS, following the instructions under `docker-run`.
+## Usage
 
-## docker-compose
+1. Build and publish a [Docker](https://www.docker.com/) image of the Web server using the instructions found under `docker-bundle`.
+2. Deploy the environment either using [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) (see [related section](#elastic-beanstalk)) or directly onto a simple [EC2 instance](https://aws.amazon.com/ec2/) (see [related section](#ec2-ubuntu)). The main difference between these two approaches is the SSL setup.
+
+## docker-bundle
 
 This section is used to create and publish a new version of Orca's Web application as a [Docker](https://www.docker.com/) image.
 
 ### Requirements
 
 You'll need to have both the [AWS CLI](https://aws.amazon.com/cli/) and the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) installed  and available.  
-The image will be published to our [AWS ECS](https://aws.amazon.com/ecs/) registry (424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca).
+The image will be published to our [AWS ECS](https://aws.amazon.com/ecs/) registry (`424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca`).
 
 You will need to be logged in using:
-```
-aws ecr get-login
+```shell-script
+aws ecr get-login | bash
 ```
 
 ### Usage
 
 - Make sure to have the webapp available under the `webapps/` directory
 - Execute `compose.bat <version>`.
 
-## docker-run
+## elastic-beanstalk
+
+This section creates a application bundle for [AWS Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) to run a [Multi-Container Docker environment](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_docker_ecs.html) with a ready-to-use Orca Web server.
 
-This section creates a application bundle for [AWS Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) to run a [multi-container Docker environment](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_docker_ecs.html) with a ready-to-use Orca Web server.
+Using Elastic Beanstalk, the SSL certificates are managed via [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) and installed on a front-facing [Elastic Load Balancer (ELB)](https://aws.amazon.com/elasticloadbalancing/). The distributed certificate is a wildcard, whose renewal is automatically handled by ACM.
+
+> - **Pro:** Easiest setup possible.
+> - **Con:** Uses an ELB (per environment), which is somewhat pricy and downright overkill, considering our current needs.
 
 ### Usage
+
+- Create an [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) environment configured as follows:
+  1. Use an Elastic Load Balancer and listen for both HTTP and HTTPS
+  2. Select [Multi-Container Docker environment](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_docker_ecs.html)
+  3. Set up the [required environment variables](#environment-variables)
 - Create a `zip` archive from the `Dockerrun.aws.json` and the `nginx-config` directory.
 - Upload to the desired [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) environment.
+
+## ec2-ubuntu
+
+This section guides you through setting up client configuration and building tools to deploy Orca directly onto an [EC2 instance]([EC2](https://aws.amazon.com/ec2/)).
+
+Managing your own EC2 instance "manually" will use certificates issued by [Let's Encrypt](https://letsencrypt.org/). It might end up somewhat more painful to manage, although their [Certbot](https://certbot.eff.org/) client is very solid when working with NGINX on Ubuntu. The distributed certificates can **not** use wildcards, and thus are issued dynamically for each instance, in turn requiring the corresponding DNS records to have properly propagated before being able to resolve the challenge.
+
+> - **Pro:** No additional costs, other than the EC2 instance and data transfer.
+> - **Con:** More complex setup.
+
+### Usage
+
+- Launch an EC2 instance configured as follows:
+  1. Choose an instance of type _Ubuntu Server_ (e.g.: `ami-a8d2d7ce`).
+  2. Set its `clientid` tag appropriately.
+  3. Pick a preconfigured [Security Group](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html) that opens HTTP (:80/tcp), HTTPS (:443/tcp) and SSH (:22/tcp).
+- Create the DNS record for `<client id>.orca-solution.com` pointing to the right instance (use an [Elastic IP](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)).
+- Set the [expected environment variables](#environment-variables):
+  1. Edit the `/ec2-ubuntu/orca.conf.tmpl`
+  2. Upload it as `<client id>.conf` in the `orca-clients` S3 bucket (`arn:aws:s3:::orca-clients`).
+- Upload the setup code to the EC2 instance:
+```shell-script
+tar -zcvf setup.tar.gz *.{conf,sh}
+scp -i /path/to/pem setup.tar.gz ubuntu@<ip>:/home/ubuntu
+```
+- Connect onto the instance via SSH for the last step
+
+> **IMPORTANT:** Ensure the DNS records have properly propagated before continuing.
+```shell-script
+tar -zxvf setup.tar.gz
+./setup.sh
+```
+
+## Environment variables
+
+| Name | Description |
+| --- | --- |
+| `AWS_ACCESS_KEY_ID`* | Access Key ID of user with full access to arn:aws:s3:::orca-resources |
+| `AWS_SECRET_KEY`* | Secret Key of user with full access to arn:aws:s3:::orca-resources |
+| `ORCA_DB_HOST`* | [RDS](https://aws.amazon.com/rds/) hostname |
+| `ORCA_DB_NAME`* | [RDS](https://aws.amazon.com/rds/) database name |
+| `ORCA_DB_USER`* | Database user name |
+| `ORCA_DB_PASS`* | Database user password |
+| `ORCA_DEMO_ENABLED` | `true` iff the demo mode should be enabled |
+| `ORCA_INIT_SECRET` | Used to trigger a (re)initialisation of the database or a demo data reset |
+
+> **\*** - Required

docker-compose/README.md → docker-bundle/README.md

@@ -1,15 +1,15 @@
-## docker-compose
+## docker-bundle
 
 This section is used to create and publish a new version of Orca's Web application as a [Docker](https://www.docker.com/) image.
 
 ### Requirements
 
 You'll need to have both the [AWS CLI](https://aws.amazon.com/cli/) and the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) installed  and available.  
-The image will be published to our [AWS ECS](https://aws.amazon.com/ecs/) registry (424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca).
+The image will be published to our [AWS ECS](https://aws.amazon.com/ecs/) registry (`424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca`).
 
 You will need to be logged in using:
-```
-aws ecr get-login
+```shell-script
+aws ecr get-login | bash
 ```
 
 ### Usage

ec2-ubuntu/README.md

@@ -0,0 +1,31 @@
+## ec2-ubuntu
+
+This section guides you through setting up client configuration and building tools to deploy Orca directly onto an [EC2 instance]([EC2](https://aws.amazon.com/ec2/)).
+
+Managing your own EC2 instance "manually" will use certificates issued by [Let's Encrypt](https://letsencrypt.org/). It might end up somewhat more painful to manage, although their [Certbot](https://certbot.eff.org/) client is very solid when working with NGINX on Ubuntu. The distributed certificates can **not** use wildcards, and thus are issued dynamically for each instance, in turn requiring the corresponding DNS records to have properly propagated before being able to resolve the challenge.
+
+> - **Pro:** No additional costs, other than the EC2 instance and data transfer.
+> - **Con:** More complex setup.
+
+### Usage
+
+- Launch an EC2 instance configured as follows:
+  1. Choose an instance of type _Ubuntu Server_ (e.g.: `ami-a8d2d7ce`).
+  2. Set its `clientid` tag appropriately.
+  3. Pick a preconfigured [Security Group](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html) that opens HTTP (:80/tcp), HTTPS (:443/tcp) and SSH (:22/tcp).
+- Create the DNS record for `<client id>.orca-solution.com` pointing to the right instance (use an [Elastic IP](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)).
+- Set the [expected environment variables](#environment-variables):
+  1. Edit the `/ec2-ubuntu/orca.conf.tmpl`
+  2. Upload it as `<client id>.conf` in the `orca-clients` S3 bucket (`arn:aws:s3:::orca-clients`).
+- Upload the setup code to the EC2 instance:
+```shell-script
+tar -zcvf setup.tar.gz *.{conf,sh}
+scp -i /path/to/pem setup.tar.gz ubuntu@<ip>:/home/ubuntu
+```
+- Connect onto the instance via SSH for the last step
+
+> **IMPORTANT:** Ensure the DNS records have properly propagated before continuing.
+```shell-script
+tar -zxvf setup.tar.gz
+./setup.sh
+```

ec2-ubuntu/certbot.conf

@@ -0,0 +1,6 @@
+rsa-key-size		= 4096
+email				= [email protected]
+agree-tos			= True
+renew-by-default	= True
+redirect			= True
+domains				= ${clientid}.orca-solution.com,${clientid}.formationssecurite.fr

ec2-ubuntu/nginx.conf

@@ -0,0 +1,13 @@
+server {
+    server_name     ${clientid}.formationssecurite.fr;
+
+    return          301 https://${clientid}.orca-solution.com;
+}
+
+server {
+    server_name     ${clientid}.orca-solution.com;
+
+    location        / {
+        proxy_pass  http://127.0.0.1:8080;
+    }
+}

ec2-ubuntu/orca.conf.tmpl

@@ -0,0 +1,10 @@
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_KEY=
+
+ORCA_DB_HOST=
+ORCA_DB_NAME=
+ORCA_DB_USER=
+ORCA_DB_PASS=
+
+ORCA_DEMO_ENABLED=
+ORCA_INIT_SECRET=

ec2-ubuntu/setup.sh

@@ -0,0 +1,74 @@
+#!/bin/sh
+set -e
+
+# Requires the ec2-orca-install IAM role to:
+# - list the current instance's tags		from ec2
+# - get client-specific configuration		from s3
+# - access the Orca docker image			from ecr
+
+printf "===============================================================================\n\
+  Setting up Orca -- this will take a minute\
+\n===============================================================================\n"
+
+# aws cli
+sudo apt-get update
+sudo apt-get install -y python-pip
+sudo pip install --upgrade awscli
+
+# configure the clientid environment variable using the "clientid" ec2 instance tag
+aws ec2 describe-tags --filters "Name=resource-id,Values=`curl -s http://169.254.169.254/latest/meta-data/instance-id`" --region eu-west-1 > .ec2-instance-tags
+sudo apt-get install -y jq
+export clientid=`jq --raw-output ".Tags[] | select(.Key==\"clientid\") | .Value" .ec2-instance-tags`
+printf "===============================================================================\n\
+  Setting up Orca for client: ${clientid:?}\
+\n===============================================================================\n"
+
+# configuration files
+aws s3 cp s3://orca-clients/${clientid}.conf orca.conf
+sed -i *.conf -e "s/\${clientid}/${clientid:?}/g"
+printf "===============================================================================\n\
+  Configuration files loaded\
+\n===============================================================================\n"
+
+# nginx
+sudo apt-get install -y nginx
+sudo cp nginx.conf /etc/nginx/conf.d/default.conf
+printf "===============================================================================\n\
+  NGINX installation completed\
+\n===============================================================================\n"
+
+# let's encrypt's certificates w/ certbot
+# see https://certbot.eff.org/#ubuntuxenial-nginx
+sudo apt-get install -y software-properties-common
+sudo add-apt-repository -y ppa:certbot/certbot
+sudo apt-get update
+sudo apt-get install -y python-certbot-nginx
+sudo certbot --nginx --config certbot.conf --non-interactive
+sudo service nginx restart
+printf "===============================================================================\n\
+  Let's Encrypt certificates installed\
+\n===============================================================================\n"
+
+# docker
+# see https://store.docker.com/editions/community/docker-ce-server-ubuntu
+sudo apt-get -y install apt-transport-https ca-certificates curl
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
+sudo add-apt-repository \
+       "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
+       $(lsb_release -cs) \
+       stable"
+sudo apt-get update
+sudo apt-get -y install docker-ce
+printf "===============================================================================\n\
+  Docker installation completed\
+\n===============================================================================\n"
+
+# orca
+sudo `aws ecr get-login --no-include-email --region eu-west-1`
+sudo docker stop orca || true && sudo docker rm orca || true
+sudo docker pull 424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca:latest
+sudo docker run -it -d -p=8080:8080 --name=orca --env-file orca.conf 424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca:latest
+
+printf "===============================================================================\n\
+  All done. Servers are up and running.\
+\n===============================================================================\n"

ec2-ubuntu/update.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+set -e
+
+# Environment must be setup beforehand using setup.sh
+
+# Requires the ec2-orca-install IAM role to:
+# - access the Orca docker image			from ecr
+
+printf "===============================================================================\n\
+  Updating Orca...\
+\n===============================================================================\n"
+
+sudo `aws ecr get-login --no-include-email --region eu-west-1`
+sudo docker stop orca || true && sudo docker rm orca || true
+sudo docker pull 424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca:latest
+sudo docker run -it -d -p=8080:8080 --name=orca --env-file orca.conf 424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca:latest
+
+printf "===============================================================================\n\
+  All done. Servers are up and running.\
+\n===============================================================================\n"

elastic-beanstalk/README.md

@@ -0,0 +1,17 @@
+## elastic-beanstalk
+
+This section creates a application bundle for [AWS Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) to run a [Multi-Container Docker environment](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_docker_ecs.html) with a ready-to-use Orca Web server.
+
+Using Elastic Beanstalk, the SSL certificates are managed via [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) and installed on a front-facing [Elastic Load Balancer (ELB)](https://aws.amazon.com/elasticloadbalancing/). The distributed certificate is a wildcard, whose renewal is automatically handled by ACM.
+
+> - **Pro:** Easiest setup possible.
+> - **Con:** Uses an ELB (per environment), which is somewhat pricy and downright overkill, considering our current needs.
+
+### Usage
+
+- Create an [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) environment configured as follows:
+  1. Use an Elastic Load Balancer and listen for both HTTP and HTTPS
+  2. Select [Multi-Container Docker environment](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_docker_ecs.html)
+  3. Set up the [required environment variables](#environment-variables)
+- Create a `zip` archive from the `Dockerrun.aws.json` and the `nginx-config` directory.
+- Upload to the desired [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) environment.