Download as
Browse Code »

Commit c8368bbf8993b6f5ab07a6b829e0eea04e9a2309

Authored by Jacob Vosmaer
2 parents 0c570a7e 8be2fbf9
Exists in master and in 13 other branches 6-8-stable, 6-8-stable-ee, 6-9-stable, 6-9-stable-ee, 7-0-stable, 7-0-stable-ee, 7-0-stable-spb, 7-1-stable, 7-1-stable-ee, 7-2-stable, 7-2-stable-ee, branch_test, nginx_ssl_tweaks

Merge branch 'this-is-nitpicking' into 'master' 

This Is Nitpicking
Showing 1 changed file with 88 additions and 82 deletions   Show diff stats
README.md
  Diff comments   View file @c8368bb
... ... @@ -13,7 +13,7 @@ Please [download the package][downloads] and follow the steps below.
13 13 ```
14 14 sudo apt-get install openssh-server
15 15 sudo apt-get install postfix # sendmail or exim is also OK
16   -sudo dpkg -i gitlab-x.y.z-omnibus-x.ubuntu.12.04_amd64.deb # this is the .deb you downloaded
  16 +sudo dpkg -i gitlab_x.y.z-omnibus-x.ubuntu.12.04_amd64.deb # this is the .deb you downloaded
17 17 sudo gitlab-ctl reconfigure
18 18 ```
19 19  
... ... @@ -24,7 +24,7 @@ sudo yum install openssh-server
24 24 sudo yum install postfix # sendmail or exim is also OK
25 25 sudo rpm -i gitlab-x.y.z_omnibus-x.el6.x86_64.rpm # this is the .rpm you downloaded
26 26 sudo gitlab-ctl reconfigure
27   -sudo lokkit -s http -s ssh # Open up the firewall for HTTP and SSH
  27 +sudo lokkit -s http -s ssh # open up the firewall for HTTP and SSH requests
28 28 ```
29 29  
30 30 ### After installation
... ... @@ -36,9 +36,7 @@ You can login as an admin user with username `root` and password `5iveL!fe`.
36 36  
37 37 For update instructions, see [the update guide](doc/update.md).
38 38  
39   -## How to manage an Omnibus-installed GitLab
40   -
41   -### Start/stop GitLab
  39 +## Starting and stopping
42 40  
43 41 You can start, stop or restart GitLab and all of its components with the
44 42 following commands.
... ... @@ -60,6 +58,8 @@ It is also possible to start, stop or restart individual components.
60 58 sudo gitlab-ctl restart unicorn
61 59 ```
62 60  
  61 +## Configuration
  62 +
63 63 ### Creating the gitlab.rb configuration file
64 64  
65 65 ```shell
... ... @@ -68,6 +68,9 @@ sudo touch /etc/gitlab/gitlab.rb
68 68 sudo chmod 600 /etc/gitlab/gitlab.rb
69 69 ```
70 70  
  71 +Below several examples are given for settings in `/etc/gitlab/gitlab.rb`.
  72 +Please restart each time you made a change.
  73 +
71 74 ### Configuring the external URL for GitLab
72 75  
73 76 In order for GitLab to display correct repository clone links to your users
... ... @@ -80,6 +83,83 @@ external_url "http://gitlab.example.com"
80 83  
81 84 Run `sudo gitlab-ctl reconfigure` for the change to take effect.
82 85  
  86 +
  87 +### Storing Git data in an alternative directory
  88 +
  89 +By default, omnibus-gitlab stores Git repository data in `/var/opt/gitlab/git-data`.
  90 +You can change this location by adding the following line to `/etc/gitlab/gitlab.rb`.
  91 +
  92 +```ruby
  93 +git_data_dir "/mnt/nas/git-data"
  94 +```
  95 +
  96 +Run `sudo gitlab-ctl reconfigure` for the change to take effect.
  97 +
  98 +### Setting up LDAP sign-in
  99 +
  100 +If you have an LDAP directory service such as Active Directory, you can configure
  101 +GitLab so that your users can sign in with their LDAP credentials. Add the following
  102 +to `/etc/gitlab/gitlab.rb`, edited for your server.
  103 +
  104 +```ruby
  105 +# These settings are documented in more detail at
  106 +# https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example#L118
  107 +gitlab_rails['ldap_enabled'] = true
  108 +gitlab_rails['ldap_host'] = 'hostname of LDAP server'
  109 +gitlab_rails['ldap_port'] = 389
  110 +gitlab_rails['ldap_uid'] = 'sAMAccountName'
  111 +gitlab_rails['ldap_method'] = 'plain' # 'ssl' or 'plain'
  112 +gitlab_rails['ldap_bind_dn'] = 'CN=query user,CN=Users,DC=mycorp,DC=com'
  113 +gitlab_rails['ldap_password'] = 'query user password'
  114 +gitlab_rails['ldap_allow_username_or_email_login'] = true
  115 +gitlab_rails['ldap_base'] = 'DC=mycorp,DC=com'
  116 +
  117 +# GitLab Enterprise Edition only
  118 +gitlab_rails['ldap_group_base'] = '' # Example: 'OU=groups,DC=mycorp,DC=com'
  119 +gitlab_rails['ldap_user_filter'] = '' # Example: '(memberOf=CN=my department,OU=groups,DC=mycorp,DC=com)'
  120 +```
  121 +
  122 +Run `sudo gitlab-ctl reconfigure` for the LDAP settings to take effect.
  123 +
  124 +### Enable HTTPS
  125 +
  126 +By default, omnibus-gitlab runs does not use HTTPS. If you want to enable HTTPS you can add the
  127 +following line to `/etc/gitlab/gitlab.rb`.
  128 +
  129 +```ruby
  130 +external_url "https://gitlab.example.com"
  131 +```
  132 +
  133 +Redirect `HTTP` requests to `HTTPS`.
  134 +
  135 +```ruby
  136 +external_url "https://gitlab.example.com"
  137 +nginx['redirect_http_to_https'] = true
  138 +```
  139 +
  140 +Change the default port and the ssl certificate locations.
  141 +
  142 +```ruby
  143 +external_url "https://gitlab.example.com:2443"
  144 +nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.crt"
  145 +nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.key"
  146 +```
  147 +
  148 +Create the default ssl certifcate directory and add the files:
  149 +
  150 +```
  151 +sudo mkdir -p /etc/gitlab/ssl && sudo chmod 700 /etc/gitlab/ssl
  152 +sudo cp gitlab.example.com.crt gitlab.example.com.key /etc/gitlab/ssl/
  153 +# run lokkit to open https on the firewall
  154 +sudo lokkit -s https
  155 +# if you are using a non standard https port
  156 +sudo lokkit -p 2443:tcp
  157 +```
  158 +
  159 +Run `sudo gitlab-ctl reconfigure` for the change to take effect.
  160 +
  161 +## Backups
  162 +
83 163 ### Creating an application backup
84 164  
85 165 To create a backup of your repositories and GitLab metadata, run the following command.
... ... @@ -138,7 +218,7 @@ If there is a GitLab version mismatch between your backup tar file and the insta
138 218 version of GitLab, the restore command will abort with an error. Install a package for
139 219 the [required version](https://www.gitlab.com/downloads/archives/) and try again.
140 220  
141   -### Invoking Rake tasks
  221 +## Invoking Rake tasks
142 222  
143 223 To invoke a GitLab Rake task, use `gitlab-rake`. For example:
144 224  
... ... @@ -150,7 +230,7 @@ Contrary to with a traditional GitLab installation, there is no need to change
150 230 the user or the `RAILS_ENV` environment variable; this is taken care of by the
151 231 `gitlab-rake` wrapper script.
152 232  
153   -### Directory structure
  233 +## Directory structure
154 234  
155 235 Omnibus-gitlab uses four different directories.
156 236  
... ... @@ -162,44 +242,7 @@ Omnibus-gitlab uses four different directories.
162 242 - `/var/log/gitlab` contains all log data generated by components of
163 243 omnibus-gitlab.
164 244  
165   -### Storing Git data in an alternative directory
166   -
167   -By default, omnibus-gitlab stores Git repository data in `/var/opt/gitlab/git-data`.
168   -You can change this location by adding the following line to `/etc/gitlab/gitlab.rb`.
169   -
170   -```ruby
171   -git_data_dir "/mnt/nas/git-data"
172   -```
173   -
174   -Run `sudo gitlab-ctl reconfigure` for the change to take effect.
175   -
176   -### Setting up LDAP sign-in
177   -
178   -If you have an LDAP directory service such as Active Directory, you can configure
179   -GitLab so that your users can sign in with their LDAP credentials. Add the following
180   -to `/etc/gitlab/gitlab.rb`, edited for your server.
181   -
182   -```ruby
183   -# These settings are documented in more detail at
184   -# https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example#L118
185   -gitlab_rails['ldap_enabled'] = true
186   -gitlab_rails['ldap_host'] = 'hostname of LDAP server'
187   -gitlab_rails['ldap_port'] = 389
188   -gitlab_rails['ldap_uid'] = 'sAMAccountName'
189   -gitlab_rails['ldap_method'] = 'plain' # 'ssl' or 'plain'
190   -gitlab_rails['ldap_bind_dn'] = 'CN=query user,CN=Users,DC=mycorp,DC=com'
191   -gitlab_rails['ldap_password'] = 'query user password'
192   -gitlab_rails['ldap_allow_username_or_email_login'] = true
193   -gitlab_rails['ldap_base'] = 'DC=mycorp,DC=com'
194   -
195   -# GitLab Enterprise Edition only
196   -gitlab_rails['ldap_group_base'] = '' # Example: 'OU=groups,DC=mycorp,DC=com'
197   -gitlab_rails['ldap_user_filter'] = '' # Example: '(memberOf=CN=my department,OU=groups,DC=mycorp,DC=com)'
198   -```
199   -
200   -Run `sudo gitlab-ctl reconfigure` for the LDAP settings to take effect.
201   -
202   -### Starting a Rails console session
  245 +## Starting a Rails console session
203 246  
204 247 For advanced users only. If you need access to a Rails production console for your
205 248 GitLab installation you can start one with the following command:
... ... @@ -210,43 +253,6 @@ sudo /opt/gitlab/bin/gitlab-rails console
210 253  
211 254 This will only work after you have run `gitlab-ctl reconfigure` at least once.
212 255  
213   -### Enable HTTPS
214   -
215   -By default, omnibus-gitlab runs does not use HTTPS. If you want to enable HTTPS you can add the
216   -following line to `/etc/gitlab/gitlab.rb`.
217   -
218   -```ruby
219   -external_url "https://gitlab.example.com"
220   -```
221   -
222   -Redirect `HTTP` requests to `HTTPS`.
223   -
224   -```ruby
225   -external_url "https://gitlab.example.com"
226   -nginx['redirect_http_to_https'] = true
227   -```
228   -
229   -Change the default port and the ssl certificate locations.
230   -
231   -```ruby
232   -external_url "https://gitlab.example.com:2443"
233   -nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.crt"
234   -nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.key"
235   -```
236   -
237   -Create the default ssl certifcate directory and add the files:
238   -
239   -```
240   -sudo mkdir -p /etc/gitlab/ssl && sudo chmod 700 /etc/gitlab/ssl
241   -sudo cp gitlab.example.com.crt gitlab.example.com.key /etc/gitlab/ssl/
242   -# run lokkit to open https on the firewall
243   -sudo lokkit -s https
244   -# if you are using a non standard https port
245   -sudo lokkit -p 2443:tcp
246   -```
247   -
248   -Run `sudo gitlab-ctl reconfigure` for the change to take effect.
249   -
250 256 ## Building your own package
251 257  
252 258 See [the separate build documentation](doc/build.md).
... ...