Added configuration instructions for Nginx/Passenger.

Alex Pardoe
1 parent c9f0e376
Showing 1 changed file with 64 additions and 0 deletions Show diff stats
README.md
@@ -380,6 +380,70 @@ sudo gitlab-rake gitlab:setup
  
 This is a destructive command; do not run it on an existing database!
  
+## Using an existing Passenger/Nginx installation
+
+In some cases you may want to host GitLab using an existing Passenger/Nginx
+installation but still have the convenience of updating and installing using
+the omnibus packages.
+
+First, you'll need to setup your `/etc/gitlab/gitlab.rb` to disable the built-in
+Nginx and Unicorn:
+
+```ruby
+# Disable the built-in nginx
+nginx['enable'] = false
+
+# Disable the built-in unicorn
+unicorn['enable'] = false
+```
+
+Make sure you run `sudo gitlab-ctl reconfigure` for the changes to take effect.
+
+Then, in your custom Passenger/Nginx installation, create the following site
+configuration file:
+
+```
+server {
+  listen *:80;
+  server_name git.yourdomain.com;
+  server_tokens off;
+  root /opt/gitlab/embedded/service/gitlab-rails/public;
+
+  client_max_body_size 250m;
+
+  access_log  /var/log/gitlab/nginx/gitlab_access.log;
+  error_log   /var/log/gitlab/nginx/gitlab_error.log;
+
+  # Ensure Passenger uses the bundled Ruby version
+  passenger_ruby /opt/gitlab/embedded/bin/ruby;
+
+  # Correct the $PATH variable to included packaged executables
+  passenger_set_cgi_param PATH "/opt/gitlab/bin:/opt/gitlab/embedded/bin:/usr/local/bin:/usr/bin:/bin";
+
+  # Make sure Passenger runs as the correct user and group to
+  # prevent permission issues
+  passenger_user git;
+  passenger_group git;
+
+  # Enable Passenger & keep at least one instance running at all times
+  passenger_enabled on;
+  passenger_min_instances 1;
+
+  error_page 502 /502.html;
+}
+```
+
+For a typical Passenger installation this file should probably
+be located at `/etc/nginx/sites-available/gitlab` and symlinked to
+`/etc/nginx/sites-enabled/gitlab`.
+
+Other than the Passenger configuration in place of Unicorn and the lack of HTTPS
+(although this could be enabled) this file is mostly identical to the
+[bundled Nginx configuration](files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb).
+
+Don't forget to restart Nginx to load the new configuration (on Debian-based
+systems `sudo service nginx restart`).
+
 ## Building your own package
  
 See [the separate build documentation](doc/build.md).
...	...	@@ -380,6 +380,70 @@ sudo gitlab-rake gitlab:setup
380	380
381	381	This is a destructive command; do not run it on an existing database!
382	382
	383	+## Using an existing Passenger/Nginx installation
	384	+
	385	+In some cases you may want to host GitLab using an existing Passenger/Nginx
	386	+installation but still have the convenience of updating and installing using
	387	+the omnibus packages.
	388	+
	389	+First, you'll need to setup your `/etc/gitlab/gitlab.rb` to disable the built-in
	390	+Nginx and Unicorn:
	391	+
	392	+```ruby
	393	+# Disable the built-in nginx
	394	+nginx['enable'] = false
	395	+
	396	+# Disable the built-in unicorn
	397	+unicorn['enable'] = false
	398	+```
	399	+
	400	+Make sure you run `sudo gitlab-ctl reconfigure` for the changes to take effect.
	401	+
	402	+Then, in your custom Passenger/Nginx installation, create the following site
	403	+configuration file:
	404	+
	405	+```
	406	+server {
	407	+ listen *:80;
	408	+ server_name git.yourdomain.com;
	409	+ server_tokens off;
	410	+ root /opt/gitlab/embedded/service/gitlab-rails/public;
	411	+
	412	+ client_max_body_size 250m;
	413	+
	414	+ access_log /var/log/gitlab/nginx/gitlab_access.log;
	415	+ error_log /var/log/gitlab/nginx/gitlab_error.log;
	416	+
	417	+ # Ensure Passenger uses the bundled Ruby version
	418	+ passenger_ruby /opt/gitlab/embedded/bin/ruby;
	419	+
	420	+ # Correct the $PATH variable to included packaged executables
	421	+ passenger_set_cgi_param PATH "/opt/gitlab/bin:/opt/gitlab/embedded/bin:/usr/local/bin:/usr/bin:/bin";
	422	+
	423	+ # Make sure Passenger runs as the correct user and group to
	424	+ # prevent permission issues
	425	+ passenger_user git;
	426	+ passenger_group git;
	427	+
	428	+ # Enable Passenger & keep at least one instance running at all times
	429	+ passenger_enabled on;
	430	+ passenger_min_instances 1;
	431	+
	432	+ error_page 502 /502.html;
	433	+}
	434	+```
	435	+
	436	+For a typical Passenger installation this file should probably
	437	+be located at `/etc/nginx/sites-available/gitlab` and symlinked to
	438	+`/etc/nginx/sites-enabled/gitlab`.
	439	+
	440	+Other than the Passenger configuration in place of Unicorn and the lack of HTTPS
	441	+(although this could be enabled) this file is mostly identical to the
	442	+[bundled Nginx configuration](files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb).
	443	+
	444	+Don't forget to restart Nginx to load the new configuration (on Debian-based
	445	+systems `sudo service nginx restart`).
	446	+
383	447	## Building your own package
384	448
385	449	See [the separate build documentation](doc/build.md).
...	...