Merge branch 'environment-variables-in-the-app' into 'master'

Environment variables in the app

Fixes #3717 and #3519 

## Why environment variables?

We need environmental variables, they are an expected way to configure apps https://medium.com/@kelseyhightower/12-fractured-apps-1080c73d481c#.ntrdiyu4c

This causes many tools and to tutorials to make it easy to set environmental variables and harder to supply a configuration file. 

So even though we agree they are not ideal https://support.cloud.engineyard.com/hc/en-us/articles/205407508-Environment-Variables-and-Why-You-Shouldn-t-Use-Them the market has spoken.

## Why for GitLab the application and not for the Omnibus packages?

Environmental variables are also needed by people that do not run our Omnibus packages, for example natively bundled apps (Debian apt-get) and idiomatic Docker packages (Mesos, Kubernetes, etc.).

Of course it should work great with Omnibus packages too so any advise is welcome in that regard.

There is an MR https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/575/diffs to be able to set any variable in gitlab.rb via environmental variables. I think both that and this MR should be merged to solve the configuration problem for both Omnibus and non-Omnibus installations. When both are merged the documentation should be crosslinked.

## Why uppercase?

Need to be all cap according to Google Shell guideline:
"Constants and Environment Variable Names => All caps, separated with underscores, declared at the top of the file."
https://google.github.io/styleguide/shell.xml#Constants_and_Environment_Variable_Names

Or as explained on http://stackoverflow.com/a/673940/613240
Keeping to this convention, you can rest assured that you don't need to know every environment variable used by UNIX tools or shells in order to avoid overwriting them. If it's your variable, lowercase it. If you export it, uppercase it.

/cc @JobV @DouweM @marin @jacobvosmaer @ayufan @pravi

See merge request !2215

2 files changed, 46 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index f40a257b42f..d82ff8b908b 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -56,6 +56,7 @@
 - [Issue closing](customization/issue_closing.md) Customize how to close an issue from commit messages.
 - [Libravatar](customization/libravatar.md) Use Libravatar for user avatars.
 - [Log system](logs/logs.md) Log system.
+- [Environmental Variables](administration/environmental_variables.md) to configure GitLab.
 - [Operations](operations/README.md) Keeping GitLab up and running
 - [Raketasks](raketasks/README.md) Backups, maintenance, automatic web hook setup and the importing of projects.
 - [Security](security/README.md) Learn what you can do to further secure your GitLab instance.
diff --git a/doc/administration/enviroment_variables.md b/doc/administration/enviroment_variables.md
new file mode 100644
index 00000000000..d7f5cb7c21f
--- /dev/null
+++ b/doc/administration/enviroment_variables.md
@@ -0,0 +1,45 @@
+# Environment Variables
+
+## Introduction
+
+Commonly people configure GitLab via the gitlab.rb configuration file in the Omnibus package.
+
+But if you prefer to use environment variables we allow that too.
+
+## Supported environment variables
+
+Variable | Type | Explanation
+--- | --- | ---
+GITLAB_ROOT_PASSWORD | string | sets the password for the `root` user on installation
+GITLAB_HOST | url | hostname of the GitLab server includes http or https
+RAILS_ENV | production/development/staging/test | Rails environment
+DATABASE_URL | url | For example: postgresql://localhost/blog_development?pool=5
+
+## Complete database variables
+
+As explained in the [Heroku documentation](https://devcenter.heroku.com/articles/rails-database-connection-behavior) the DATABASE_URL doesn't let you set:
+
+- adapter
+- database
+- username
+- password
+- host
+- port
+
+To do so please `cp config/database.yml.env config/database.yml` and use the following variables:
+
+Variable | Default
+--- | ---
+GITLAB_DATABASE_ADAPTER | postgresql
+GITLAB_DATABASE_ENCODING | unicode
+GITLAB_DATABASE_DATABASE | gitlab_#{ENV['RAILS_ENV']
+GITLAB_DATABASE_POOL | 10
+GITLAB_DATABASE_USERNAME | root
+GITLAB_DATABASE_PASSWORD |
+GITLAB_DATABASE_HOST | localhost
+GITLAB_DATABASE_PORT | 5432
+
+## Other variables
+
+We welcome merge requests to make more settings configurable via variables.
+Please stick to the naming scheme "GITLAB_#{name 1_settings.rb in upper case}".