1 I transitioned from [Apache][] to [Nginx][] a week or so ago, since
2 words like “minimal” and “streamlined” are appealing to me ;). I was
3 quite happy with Apache, but it's always nice to try something new.
4 Anyhow here's a quick review my configuration.
6 On [[Gentoo]], set the the [modules][] you want to install by adding
7 the following lines to your `/etc/make.conf`:
9 NGINX_MODULES_HTTP="access auth_basic autoindex charset fastcgi gzip gzip_static limit_req map proxy rewrite scgi ssi stub_status"
12 Then install Nginx with:
16 Make any adjustments you like to `/etc/nginx/mime.types`. I added:
20 application/x-python py;
21 application/x-shell sh;
25 Now it's time to setup `/etc/nginx/nginx.conf`. Poking about online
26 will give you lots of examples. Here are things that were useful to
27 me, in the order they appear in the `http` block of my `nginx.conf`.
29 Redirecting `www.example.com` to `example.com`
30 ==============================================
32 This keeps people who accidentally add a `www.` prefix to your URL
33 from matching the wildcard virtual host block defined below.
36 # www.example.com -> example.com
39 server_name www.example.com;
40 ssl_certificate /etc/ssl/nginx/www.example.com.pem;
41 ssl_certificate_key /etc/ssl/nginx/www.example.com-key.pem;
42 rewrite ^/(.*)$ $scheme://example.com/$1 permanent;
45 Gitweb (and general CGI approach)
46 =================================
52 server_name git.example.com;
54 access_log /var/log/nginx/git.example.com.access_log main;
55 error_log /var/log/nginx/git.example.com.error_log info;
57 root /usr/share/gitweb/;
61 location /gitweb.cgi {
62 include fastcgi_params;
63 fastcgi_pass unix:/var/run/fcgiwrap.sock-1;
67 Because Nginx lacks built-in [[CGI]] support, we need some tricks to
68 get `gitweb.cgi` working. We use the [fcgi module][fcgi] to pass the
69 requests on to a FastCGI server which wraps `gitweb.cgi`. On
70 [[Gentoo]], I installed the following packages:
72 * `www-misc/fcgiwrap`, a [[FastCGI]] server for wrapping [[CGI]] scripts
73 * `www-servers/spawn-fcgi`, a [[FastCGI]] manager for spawning `fcgiwrap`.
75 Configure `spawn-fcgi` to launch `fcgiwrap` with:
77 # cp /etc/conf.d/spawn-fcgi /etc/conf.d/spawn-fcgi.fcgiwrap
78 # emacs /etc/conf.d/spawn-fcgi.fcgiwrap
79 # cat /etc/conf.d/spawn-fcgi.fcgiwrap
80 FCGI_SOCKET=/var/run/fcgiwrap.sock
83 FCGI_PROGRAM=/usr/sbin/fcgiwrap
86 FCGI_EXTRA_OPTIONS="-M 0700"
87 ALLOWED_ENV="PATH HOME"
92 # ln -s spawn-fcgi spawn-fcgi.fcgiwrap
94 Start `fcgiwrap` with:
96 # /etc/init.d/spawn-fcgi.fcgiwrap start
98 Add it to the default runlevel with:
100 # rc-update add spawn-fcgi.fcgiwrap default
102 If you also want a virtual host serving Git over HTTP, you can add a
106 # http-git.example.com
108 server_name http-git.example.com;
110 access_log /var/log/nginx/http-git.example.com.access_log main;
111 error_log /var/log/nginx/http-git.example.com.error_log info;
114 include fastcgi_params;
115 fastcgi_param SCRIPT_FILENAME /usr/libexec/git-core/git-http-backend;
116 fastcgi_param GIT_HTTP_EXPORT_ALL "";
117 fastcgi_param GIT_PROJECT_ROOT /var/git;
118 fastcgi_param PATH_INFO $document_uri;
119 fastcgi_pass unix:/var/run/fcgiwrap.sock-1;
123 This uses the same FastCGI server we used for gitweb, but this time
124 the backend CGI script is `git-http-backend`.
126 Wildcard virtual hosts
127 ======================
129 To add support for virual hosts stored under `/var/www/$host`, use:
135 server_name star.example.com *.example.com;
137 access_log /var/log/nginx/star.example.com.access_log main;
138 error_log /var/log/nginx/star.example.com.error_log info;
140 #ssl_certificate /etc/ssl/nginx/$host.pem;
141 #ssl_certificate_key /etc/ssl/nginx/$host.key;
143 root /var/www/$host/htdocs;
145 # deny access to .htaccess files
151 Then adding a new host is as simple as creating a new entry in
152 `/var/www/` and updating your [[DNS]] to get the new name pointed at
153 your server. Unfortunately, [[SSL/TLS|GnuTLS]] doesn't work with this
154 approach. It appears that certificates and keys are loaded when Nginx
155 starts up, but `$host` is only defined after a request is received.
156 Nginx does support [[SNI]] though, so it will work if you write SSL
157 entries by hand for hosts that need them.
162 The configuration for my main host is more complicated, so I'll
163 intersperse some more comments. I setup both clear-text and SSL in
164 the same definition using the [SSL module][SSL]. The `_` server name
165 is a special name that matches any requests which haven't already
166 matched and been handled by an earlier `server`.
169 # catchall virtual host (optional SSL, example.com)
170 listen 80 default_server;
171 listen 443 default_server ssl;
174 ssl_certificate /etc/ssl/nginx/example.com.pem;
175 ssl_certificate_key /etc/ssl/nginx/example.com-key.pem;
177 Nothing special with the logging or root.
179 access_log /var/log/nginx/example.com.access_log main;
180 error_log /var/log/nginx/example.com.error_log info;
182 root /var/www/example.com/htdocs;
184 Turn on [[SSI]], and also use `index.shtml` as index pages.
186 index index.html index.shtml;
189 Use the [proxy module][proxy] to pass requests for `/cookbook/` and
190 subdirectories on to their [[underlying Django app|cookbook]].
192 location /cookbook/ {
193 proxy_pass http://localhost:33333/cookbook/;
194 proxy_set_header X-Real-IP $remote_addr;
197 Use the [scgi module][scgi] to pass requests for `/gallery/` and
198 subdirectories on to their [[underlying SCGI app|gallery]].
202 scgi_pass localhost:4000;
205 Turn on autoindexing for `/RAD/` and subdirectories using the
206 [autoindex module][autoindex].
212 Force SSL/TLS for `/tree/` and subdirectories, redirecting plain-text
213 requests to the equivalent HTTPS page. Use the [auth_basic
214 module][auth_basic] for authentication, the [SSL module][SSL] for
215 `$ssl_protocol`, and the [rewrite module][rewrite] for the
219 auth_basic "Family Tree";
220 auth_basic_user_file /home/jdoe/htpasswd;
221 if ($ssl_protocol = "") {
222 rewrite ^ https://example.com$request_uri? permanent;
226 Nothing special with the end of this `server` block.
228 # deny access to .htaccess files
234 [Apache]: http://www.apache.org/
235 [Nginx]: http://nginx.org/
236 [modules]: http://wiki.nginx.org/Modules
237 [fcgi]: http://wiki.nginx.org/HttpFcgiModule
238 [SSL]: http://wiki.nginx.org/HttpSslModule
239 [proxy]: http://wiki.nginx.org/HttpProxyModule
240 [scgi]: http://wiki.nginx.org/HttpScgiModule
241 [autoindex]: http://wiki.nginx.org/HttpAutoindexModule
242 [auth_basic]: http://wiki.nginx.org/HttpAuthBasicModule
243 [rewrite]: http://wiki.nginx.org/HttpRewriteModule