Bug 1361439 - Create dockerflow-compliant container that runs a BMO web head

1 files changed, 97 insertions, 6 deletions

diff --git a/README.rst b/README.rst
index 322b04ea8..c1f3f8bfe 100644
--- a/README.rst
+++ b/README.rst
@@ -4,14 +4,25 @@ BMO: bugzilla.mozilla.org
 
 BMO is Mozilla's highly customized version of Bugzilla.
 
+.. contents::
+..
+    1  Using Vagrant (For Development)
+      1.1  Setup Vagrant VMs
+      1.2  Making Changes and Seeing them
+      1.3  Technical Details
+    2  Docker Container
+      2.1  Container Arguments
+      2.2  Environmental Variables
+      2.3  Persistent Data Volume
+
 If you are looking to run Bugzilla, you should see
 https://github.com/bugzilla/bugzilla.
 
 If you want to contribute to BMO, you can fork this repo and get a local copy
-of BMO running in a few minutes.
+of BMO running in a few minutes using Vagrant.
 
-Install Vagrant
-===============
+Using Vagrant (For Development)
+===============================
 
 You will need to install the following software:
 
@@ -27,7 +38,7 @@ For Ubuntu 16.04, download the vagrant .dpkg directly from
 https://vagrantup.com.  The one that ships with Ubuntu is too old.
 
 Setup Vagrant VMs
-=================
+-----------------
 
 From your BMO checkout run the following command:
 
@@ -50,7 +61,7 @@ You can login as vagrant@bmo-web.vm with the password "vagrant01!" (without
 quotes).
 
 Making Changes and Seeing them
-==============================
+------------------------------
 
 After editing files in the bmo directory, you will need to run
 
@@ -66,7 +77,7 @@ or db is changed, do a full provision:
     vagrant rsync && vagrant provision
 
 Technical Details
-=================
+-----------------
 
 This Vagrant environment is a very complete but scaled-down version of
 production BMO.  It uses roughly the same RPMs (from CentOS 6, versus RHEL 6
@@ -82,3 +93,83 @@ Most of the cron jobs and the jobqueue daemon are running.  It is also
 configured to use memcached.
 
 The push connector is not currently configured, nor is the Pulse publisher.
+
+
+Docker Container
+================
+
+This repository is also a runnable docker container.
+
+Container Arguments
+-------------------
+
+Currently, the entry point takes a single command argument.
+This can be **httpd** or **shell**.
+
+httpd
+    This will start apache listening for connections on ``$PORT``
+shell
+    This will start an interactive shell in the container. Useful for debugging.
+
+
+Environmental Variables
+-----------------------
+
+PORT
+  This must be a value >= 1024. The httpd will listen on this port for incoming
+  plain-text HTTP connections.
+
+BMO_db_driver
+  What SQL database to use. Default is mysql. List of supported databases can be
+  obtained by listing Bugzilla/DB directory - every module corresponds to one
+  supported database and the name of the module (before ".pm") corresponds to a
+  valid value for this variable.
+
+BMO_db_host
+  The DNS name or IP address of the host that the database server runs on.
+
+BMO_db_name
+  The name of the database.
+
+BMO_db_user
+  The database user to connect as.
+
+BMO_db_pass
+  The password for the user above.
+
+BMO_site_wide_secret
+  This secret key is used by your installation for the creation and
+  validation of encrypted tokens. These tokens are used to implement
+  security features in Bugzilla, to protect against certain types of attacks.
+  It's very important that this key is kept secret. 
+
+BMO_inbound_proxies
+  This is a list of IP addresses that we expect proxies to come from.
+  This can be '*' if only the load balancer can connect to this container.
+  Setting this to '*' means that BMO will trust the X-Forwarded-For header.
+
+BMO_memcached_namespace
+  The global namespace for the memcached servers.
+
+BMO_memcached_servers
+  A list of memcached servers (ip addresses or host names). Can be empty.
+ 
+BMO_shadowdb
+  The database name of the read-only database.
+
+BMO_shadowdbhost
+  The hotname or ip address of the read-only database.
+
+BMO_shadowdbport
+   The port of the read-only database.
+
+BMO_apache_size_limit
+  This is the max amount of unshared memory (in kb) that the apache process is
+  allowed to use before Apache::SizeLimit kills it.
+
+Persistent Data Volume
+----------------------
+
+This container expects /app/data to be a persistent, shared, writable directory
+owned by uid 10001. This must be a shared (NFS/EFS/etc) volume between all
+nodes.