Merge branch 'master' of github.com:bcgov/eDivorce

openshift/README.md

@@ -1,152 +1,291 @@
-# eDivorce Environments
+# A Quickstart Guide to Setting Up eDivorce on OpenShift
 
-There are several environments set up for different purposes within OpenShift. They are available at the URLs below.
+There are three deployment environments set up for different purposes within OpenShift. They are available at the URLs below.
 
 |Environment| URL |Justice URL|
-|-----------|-----|-----|
-|DEV|edivorce-dev.pathfinder.gov.bc.ca|justice.gov.bc.ca/divorce-dev|
-|TEST|edivorce-test.pathfinder.gov.bc.ca|justice.gov.bc.ca/divorce-test|
-|PROD|edivorce-prod.pathfinder.gov.bc.ca|justice.gov.bc.ca/divorce|
+|-----------|-----|-----------|
+|DEV|[https://edivorce-dev.pathfinder.gov.bc.ca]|[https://justice.gov.bc.ca/divorce-dev]|
+|TEST|[https://edivorce-test.pathfinder.gov.bc.ca]|[https://justice.gov.bc.ca/divorce-test]|
+|PROD|[https://edivorce-prod.pathfinder.gov.bc.ca]|[https://justice.gov.bc.ca/divorce]|
 
+These instructions assume you have 4 EMPTY projects created in OpenShift:
 
-# How to access Jenkins for eDivorce
+- jag-csb-edivorce-tools (BUILD)
+- jag-csb-edivorce-dev (DEV)
+- jag-csb-edivorce-test (TEST)
+- jag-csb-edivorce-prod (PROD)
 
-- Login to https://edivorce-jenkins.pathfinder.gov.bc.ca with the username/password that was provided to you.
-
-# How to access OpenShift for eDivorce
+## How to Access OpenShift for eDivorce
 
-## Web UI
+### Web UI
 - Login to https://console.pathfinder.gov.bc.ca:8443; you'll be prompted for GitHub authorization.  You must be part of the BCDevOps Github organization, and you must have access to the eDivorce projects.
 
-## Command-line (```oc```) tools
+### Command-line (```oc```) tools
 - Download OpenShift [command line tools](https://github.com/openshift/origin/releases/download/v1.2.1/openshift-origin-client-tools-v1.2.1-5e723f6-mac.zip), unzip, and add ```oc``` to your PATH.
 - Copy command line login string from https://console.pathfinder.gov.bc.ca:8443/console/command-line.  It will look like ```oc login https://console.pathfinder.gov.bc.ca:8443 --token=xtyz123xtyz123xtyz123xtyz123```
 - Paste the login string into a terminal session.  You are no authenticated against OpenShift and will be able to execute ```oc``` commands. ```oc -h``` provides a summary of available commands.
 
-# Project contents
-
-- The "edivorce-tools" project contains the Jenkins instance and the other jsg-csb-edivorce-* projects contain different "environments".  The names are self-explanatory.
-
 
-# Uploading Templates into OpenShift
+## Uploading Templates into OpenShift
 
 1. Clone the project from Github, and then ```cd``` into the openshift/templates directory.
 
-2. Log into the OpenShift Console to get your command line token.  Then log into OpenShift from the command line.
-
-3. Upload the templates into OpenShift with the following commands (this can also be done via the web interface)
-
-```
-oc create -f ../jenkins/jenkins-pipeline-persistent-template.json -n jag-csb-edivorce-tools
-oc create -f edivorce-build-template.yaml -n jag-csb-edivorce-tools
-oc create -f nginx-build-template.yaml -n jag-csb-edivorce-tools
-oc create -f ../jenkins/pipeline.yaml -n jag-csb-edivorce-tools
+2. Log into the OpenShift console to get your command line token.  Then log into OpenShift from the command line.
 
-oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-dev
-oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-test
-oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-prod
+3. Upload the templates into OpenShift with the following commands
 
-oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-dev
-oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-test
-oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-prod
+    Tools templates
+    ```
+    oc create -f ../jenkins/jenkins-pipeline-persistent-template.json -n jag-csb-edivorce-tools
+    oc create -f edivorce-build-template.yaml -n jag-csb-edivorce-tools
+    oc create -f nginx-build-template.yaml -n jag-csb-edivorce-tools
+    oc create -f ../jenkins/pipeline.yaml -n jag-csb-edivorce-tools
+    ```
 
-```
+    Main eDivorce environment template
+    ```
+    oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-dev
+    oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-test
+    oc create -f edivorce-environment-template.yaml -n jag-csb-edivorce-prod
+    ```
 
+    NGINX proxy template
+    ```
+    oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-dev
+    oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-test
+    oc create -f nginx-environment-template.yaml -n jag-csb-edivorce-prod
+    ```
 
-# Setting up the Tools Project
+## Setting up the Tools Project
 
-Install Docker Toolbox on your computer
+### Install Docker on your computer
 
-Open Docker QuickStart Terminal (need Docker engine started and env variables set) and build the S2I image:
+### Build the S2I image:
 
 ```docker build -t s2i-nginx git://github.com/BCDevOps/s2i-nginx```
 
-Tag and push this image to the OpenShift Docker Registry for your OpenShift Project:
+### Tag and push this image to the OpenShift Docker Registry for your OpenShift Project:
 
-```docker tag s2i-nginx docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx```
+```
+docker tag s2i-nginx docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx
 
-```docker login docker-registry.pathfinder.gov.bc.ca -u <username> -p <token>```
+docker login docker-registry.pathfinder.gov.bc.ca -u <username> -p <token>
 
-```docker push docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx```
+docker push docker-registry.pathfinder.gov.bc.ca/jag-csb-edivorce-tools/s2i-nginx
+```
 
 (your docker token is the same as your OpenShift login token)
 
+###  Process the templates in the 'tools' project
 
+#### These can be processed from the commandline
 ```
 oc project jag-csb-edivorce-tools
 
 oc process jenkins-pipeline-persistent | oc create -f -
 oc process edivorce-build | oc create -f -
 oc process nginx-build | oc create -f -
-
 ```
 
-Select "Add to Project"
+#### For some reason the edivorce-build-pipeline template can't be processed from the command line like the other templates
 
-On the Browse Catalog tab, type "edivorce-build-pipeline" into the filter field.  Select the template. Create.
-(For some reason this can't be done from the command line like the other templates)
+1. Log into the web console ang go to the :"eDivorce App (tools)" project
 
+2. Select "Add to Project" from the web interface
 
+3. On the Browse Catalog tab, type "edivorce-build-pipeline" into the filter field.  Select the template.
 
-# Setting up Dev/Test/Prod Projects
+4. Create
 
-1. Give the dev/test/prod projects access to ImageStreams stored in the tools project
+5. Delete the extra services that OpenShift automatically created when you processed the edivorce-build-template. We are using perisistent storage for Jenkins.  These are ephemeral.
 
     ```
-    oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-dev:default -n jag-csb-edivorce-tools
-    oc policy add-role-to-user edit system:serviceaccount: jag-csb-edivorce-tools:default -n jag-csb-edivorce-dev
-
-    oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-test:default -n jag-csb-edivorce-tools
-    oc policy add-role-to-user edit system:serviceaccount: jag-csb-edivorce-tools:default -n jag-csb-edivorce-test
+    oc project jag-csb-edivorce-tools
 
-    oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-prod:default -n jag-csb-edivorce-tools
-    oc policy add-role-to-user edit system:serviceaccount: jag-csb-edivorce-tools:default -n jag-csb-edivorce-prod
+    oc delete svc jenkins-pipeline-svc
+    oc delete deploymentconfig jenkins-pipeline-svc
+    oc delete route jenkins-pipeline-svc
     ```
 
-2. In the web console, go into the project you want to configure
+### Add the webhook to GitHub
 
-3. Select "Add to Project"
+1. Log into the web console ang go to the :"eDivorce App (tools)" project
 
-4. On the Browse Catalog tab, type "edivorce" into the filter field.  Select the edivorce template.
+2. Select Builds => Pipelines => build-and-deploy-to-dev => Configuration
 
-    You need to enter values for the following fields:
-    ```
-        Type of environnment (dev,test or prod).
-            - Type the word dev, test, or prod
-
-        Network of upstream proxy
-            - This is used to ensure that requests come from the Justice Proxy only. It
-              should be entered in IPV4 CIDR notation e.g. 10.10.15.10/16. (The actual
-              value you need to enter cannot be stored on Github because this would
-              violate BC Government Github policies. However the PROXY_NETWORK setting
-              is currently the same for all 3 environemts [dev/test/prod] )
-    ```
+3. Copy the GitHub wookhook URL
 
-5. Select "Add to Project" again
+4. Go to the repository settings in Github, and add the webhook url under "Webhooks"
+-- Payload URL = The URL you copied from OpenShift
+-- Content type = application/json
+-- Secret = Leave Blank
+-- Just push the event
+-- Active
 
-6. On the Browse Catalog tab, type "nginx" into the filter field.  Select the nginx template
+## Setting up Dev/Test/Prod Projects
 
-    You need to enter values for the following fields:
+### Important Configuration Options
 
-    ```
-        Type of environnment (dev,test or prod).
-            - Type the word dev, test, or prod
-    ```
+#### Mandatory Settings:
+
+**PROXY_NETWORK:**
+
+Network of upstream proxy. This is used to ensure that requests come from
+the Justice Proxy only. It should be entered in IPV4 CIDR notation
+e.g. 10.10.15.10/16. The actual value you need to enter cannot be stored on Github
+because this would violate BC Government Github policies. The PROXY_NETWORK
+setting is currently the same for all 3 environments (dev, test & prod)
+
+#### Optional Settings you will probably want to set:
 
-7. Weasyprint doesn't deploy itself by default. (outstanding issue).  Go to Applications => Deployments => weasyprint and press the 'Deploy' button.
+**BASICAUTH_ENABLED:**
 
+Turns on simple basic authentication for test and dev environments.
+This is recommended since these environments are accessible to the general public.
+Set it to "True" (no quotes) to enable it.  Default = False
 
-# Data management operations
+**BASICAUTH_USERNAME / BASICAUTH_PASSWORD:**
 
-You can either use the terminal window in the OpenShift console or the ```oc rsh``` command to get to the command line on the postgresql pod.
+Username will default to divorce, and password will default to a random 16 digit string
+unless you override these settings
+
+### Setting up Dev
+
+Tag the builds in the tools project so they can be deployed to dev
+```
+oc project jag-csb-edivorce-tools
+oc tag edivorce-django:latest edivorce-django:deploy-to-dev
+oc tag nginx-proxy:latest nginx-proxy:deploy-to-dev
+```
+
+Give the dev project access to Docker images stored in the tools project
+```
+oc project jag-csb-edivorce-dev
+oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-dev:default -n jag-csb-edivorce-tools
+oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:default -n jag-csb-edivorce-dev
+```
+
+Deploy the Django app and the Postgresql DB
+```
+oc process edivorce -v ENVIRONMENT_TYPE=dev,PROXY_NETWORK=123.45.67.89/0,BASICAUTH_ENABLED=True | oc create -f -
+```
+
+Deploy the NGINX proxy
+```
+oc process nginx -v ENVIRONMENT_TYPE=dev | oc create -f -
+```
+
+Deploy Weasyprint
+```
+oc deploy weasyprint --latest
+```
+
+Give the Jenkins build pipeline access to the dev project
+```
+oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:jenkins -n jag-csb-edivorce-dev
+```
+
+
+### Setting up Test
+
+Tag the builds in the tools project so they can be deployed to test
+```
+oc project jag-csb-edivorce-tools
+oc tag edivorce-django:latest edivorce-django:deploy-to-test
+oc tag nginx-proxy:latest nginx-proxy:deploy-to-test
+```
+
+Give the test project access to Docker images stored in the tools project
+```
+oc project jag-csb-edivorce-test
+oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-test:default -n jag-csb-edivorce-tools
+oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:default -n jag-csb-edivorce-test
+```
+
+Deploy the Django app and the Postgresql DB
+```
+oc process edivorce -v ENVIRONMENT_TYPE=test,PROXY_NETWORK=123.45.67.89/0,BASICAUTH_ENABLED=True | oc create -f -
+```
+
+Deploy the NGINX proxy
+```
+oc process nginx -v ENVIRONMENT_TYPE=test | oc create -f -
+```
+
+Deploy Weasyprint
+```
+oc deploy weasyprint --latest
+```
+
+Give the Jenkins build pipeline access to the test project
+```
+oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:jenkins -n jag-csb-edivorce-test
+```
+
+### Setting up Prod
+
+Tag the builds in the tools project so they can be deployed to prod
+```
+oc project jag-csb-edivorce-tools
+oc tag edivorce-django:latest edivorce-django:deploy-to-prod
+oc tag nginx-proxy:latest nginx-proxy:deploy-to-prod
+```
+
+Give the prod project access to Docker images stored in the tools project
+```
+oc project jag-csb-edivorce-prod
+oc policy add-role-to-user system:image-puller system:serviceaccount:jag-csb-edivorce-prod:default -n jag-csb-edivorce-tools
+oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:default -n jag-csb-edivorce-prod
+```
+
+Deploy the Django app and the Postgresql DB
+```
+oc process edivorce -v ENVIRONMENT_TYPE=prod,PROXY_NETWORK=123.45.67.89/0 | oc create -f -
+```
+
+Deploy the NGINX proxy
+```
+oc process nginx -v ENVIRONMENT_TYPE=prod | oc create -f -
+```
+
+Deploy weasyprint
+```
+oc deploy weasyprint --latest
+```
+
+Give the Jenkins build pipeline access to the prod project
+```
+oc policy add-role-to-user edit system:serviceaccount:jag-csb-edivorce-tools:jenkins -n jag-csb-edivorce-prod
+```
+
+
+## Data management operations
+
+If you need to access the DB, you can either use the terminal window in the OpenShift console or the ```oc rsh```
+command to get to the command line on the postgresql pod.
+
+### You can find the current name of the postgresql pod in the web console
+
+The pod identifiers change with every deployment, you need to find the current one
 
 ```
 oc rsh postgresql-2-qp0oh
+```
+
 
+### Sample postgresql terminal session
+```
 psql -d default
 
 \dt
 
+select count(*) from core_bceiduser;
+
 \q
+
+exit
 ```
- ** the pod identifiers change regularly, you need to find the current one
+
+## How to access Jenkins for eDivorce
+
+- Login to https://edivorce-jenkins.pathfinder.gov.bc.ca with the username/password that was provided to you.