From 242417c60964331a19ae89e40e534f87ab4625b0 Mon Sep 17 00:00:00 2001
From: Jacob Vosmaer <contact@jacobvosmaer.nl>
Date: Sun, 16 Feb 2014 19:23:09 +0100
Subject: [PATCH] Add documentation for the external_url option

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 700fb47..1762d03 100644
--- a/README.md
+++ b/README.md
@@ -32,26 +32,60 @@ sudo lokkit -s http -s ssh
 
 ### Administrative commands
 
-You can make configuration changes by editing `/etc/gitlab/gitlab.rb` and
-`/etc/gitlab/gitlab-secrets.json`, followed by running
+#### Start/stop GitLab
 
+You can start, stop or restart GitLab and all of its components with the
+following commands.
+
+```shell
+# Start all GitLab components
+sudo gitlab-ctl start
+
+# Stop all GitLab components
+sudo gitlab-ctl stop
+
+# Restart all GitLab components
+sudo gitlab-ctl restart
 ```
-sudo gitlab-ctl reconfigure
+
+It is also possible to start, stop or restart individual components.
+
+```shell
+sudo gitlab-ctl restart unicorn
+```
+
+#### Creating the gitlab.rb configuration file
+
+```shell
+sudo mkdir -p /etc/gitlab
+sudo touch /etc/gitlab/gitlab.rb
+sudo chmod 600 /etc/gitlab/gitlab.rb
 ```
 
-To start/stop a component of GitLab run e.g.
-`sudo gitlab-ctl stop sidekiq`. To permanently disable e.g. Sidekiq, add
-`sidekiq['enable'] = false` to `/etc/gitlab/gitlab.rb`, and run
-`sudo gitlab-ctl reconfigure` for the change to take effect.
+#### Configuring the external URL for GitLab
 
-To invoke a GitLab rake task, use `gitlab-rake`. For example:
+In order for GitLab to display correct repository clone links to your users
+it needs to know the URL under which it is reached by your users, e.g.
+`http://gitlab.example.com`. Add the following line to `/etc/gitlab/gitlab.rb`:
 
+```ruby
+external_url "http://gitlab.example.com"
 ```
+
+Run `sudo gitlab-ctl reconfigure` for the change to take effect.
+
+
+#### Invoking Rake tasks
+
+To invoke a GitLab Rake task, use `gitlab-rake`. For example:
+
+```shell
 sudo gitlab-rake gitlab:backup:create
 ```
 
-There is no need to change the user or the `RAILS_ENV` environment variable;
-this is taken care of by the `gitlab-rake` wrapper script.
+Contrary to with a traditional GitLab installation, there is no need to change
+the user or the `RAILS_ENV` environment variable; this is taken care of by the
+`gitlab-rake` wrapper script.
 
 ### Directory structure
 
--
libgit2 0.21.2