• web

Nginx Official documentation

Nginx is an open source reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer, HTTP cache, and a Web server.


  • PHP app

          - id: my_vhost_php
            domain: mydomain.com
            indexes: index.php
              - uri: '~ \.php$'
                type: fastcgi
                to: localhost:9001

    We here define a vhost that will answer to the mydomain.com domain and will pass all requests which URL ends up with .php to a fastcgi process listening on http://localhost:9001 (Typically a php-fpm process).

    This configuration will generate the following Nginx configuration file (also linked and enabled in sites-enabled):


    server {
        listen   80;
        root /var/www/my_vhost_php;
        index index.php index.html index.htm;
        access_log /var/log/nginx/my_vhost_php-access.log;
        error_log /var/log/nginx/my_vhost_php-error.log;
        # Make site accessible from http://localhost/
        # server_name _;
        server_name mydomain.com;
        location ~ \.php$ {
            # Route type: fastcgi
            fastcgi_pass localhost:9001;
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            # NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
            fastcgi_index index.php; 
            include fastcgi_params;
  • Node.js app

          - id: my_vhost_node
            domain: mydomain.com
              - uri: '/'
                type: proxy
                to: localhost:3000

    We here define a vhost that will answer to the mydomain.com domain and will proxy all requests to a http process listening on http://localhost:3000 (Typically your Node.js service).


    server {
        listen   80;
        root /var/www/my_vhost_node;
        index index.html index.htm;
        access_log /var/log/nginx/my_vhost_node-access.log;
        error_log /var/log/nginx/my_vhost_node-error.log;
        # Make site accessible from http://localhost/
        # server_name _;
        server_name mydomain.com;
        location / {
            # Route type: proxy
            proxy_pass localhost:3000;
            proxy_pass_header Set-Cookie;


Save for a few settings, you'll most likely end up adding vhosts to your Nginx configuration.

In a nutshell, each vhost defines a directory of files, where your application or Web site resides, and a list of domains associated with it. Whenever you add a vhost, we'll create a Web root associated with its id: var/www/{vhost_id} where {vhost_id} is the id of your vhost.

You can use the webroot if you're serving files out of a sub-folder of the default Web root. For example, if you serve files out of the public/ subfolder of your app, adding the webroot: public to your vhost will make it serve files out of the /var/www/my_vhost/public folder.


Routes allow you to define a list of ways to handle different types of requests, based on the uri (order matter, first routes in the list have precedence). These routes have a type attribute:

  • custom (default): routes of this type have a custom attribute that will take the content of a regular Nginx location block.
  • fastcgi: sends requests to a fastcgi backend or upstream. Common for PHP apps.
  • proxy: sends requests to a http proxy (local or remote). Common for node.js apps.
  • websocket: assumes requests are handled as websocket traffic.
  • uwsgi: sends requests to a uwsgi service. Common for Python apps.
  • static: serves files as static assets without any processing.

You can add supported technologies with the support attribute. This attribute willl help your vhost figure out what index to serve. By default it includes index.html and index.html, adding php to support will extend it to index.php.


devops nginx start
Starts Nginx.
devops nginx stop
Stops Nginx.
devops nginx reload
Reloads the Nginx configuration and performs a graceful restart.
devops nginx restart
Restarts Nginx and reload the configuration (this will kill existing connections).
devops nginx vhost add
Adds a virtual host.


Name Type Description Required
id object Adds a virtual host. Use the same attributes as for a vhost in the configuration. Required
devops nginx vhost remove
Removes a vhost and restarts Nginx if needed. If `purge` is set to true, removes the associate webroot.


Name Type Description Required
id string The ID of your nginx domain Required
purge boolean Whether or not delete the associated webroot (/var/www/{vhost_id})


events.worker_connections integer
Number of concurrent http connection handled per nginx process
Default: 1024
http.access_log string
Global access log file path
Default: /var/log/nginx/access.log
http.error_log string
Global error log file path
Default: /var/log/nginx/error.log
http.gzip string
Enable gzip compression
Default: on
http.gzip_disable string
Space separated list of browser to disable gzip compression for
Default: msie6
http.keepalive_timeout integer
Keepalive timeout (sec) - 0 to disable
Default: 65
http.sendfile string
Enable sendfile
Default: on
http.tcp_nodelay string
Enable tcp_nodelay
Default: on
http.tcp_nopush string
Enable tcp_nopush
Default: on
http.types_hash_max_size integer
Maximum size of hash tables
Default: 2048
pid string
Pid file path
Default: /var/run/nginx.pid
user string
Nginx running user.
Default: www-data
vhosts array
Array of virtual hosts objects
vhost.aliases string
Space separated list of domain name aliases
vhost.domain string
Primary domain name, use '_' as wildcard to respond to every domain / IP
Default: _
vhost.id string
Virtual host identifier, used to perform lookup in the vhosts array. Also used to name the configuration files and the default web root.
vhost.indexes string
List indexes space separated.
Default: index.html index.htm
vhost.port integer
Listening port (TCP/80 by default, TCP/443 if SSL is enabled)
Default: 80
vhost.routes array
List of route objects. The order matters and the routes will be applied sequentially.
route.custom string
Custom inline nginx config to include within the route (e.g. auth, custom timeout)
route.static string
For type static only, define how to consider the source folder - alias or root
Default: root
route.to string
Either an upstream name, or a service / url, or a path
route.type string
The type of handler for that route
Default: custom
route.uri string
Any string / regex that nginx understand as a `location`
vhost.ssl object
Enable HTTPS
vhost.ssl.certificate string
HTTPS certificate file path (chained if needed)
Default: /etc/nginx/ssl/{domain}.pem
vhost.ssl.private_key string
Private key file path used to generate the certificate (password-less)
Default: /etc/nginx/ssl/{domain}.key
vhost.upstreams array
list of upstream objects
upstream.backends array
List of backends associated with the upstream
upstream.name string
Name of the upstream - it must be unique on the entire node
vhost.webroot string
Subfolder to serve data from based on the root /var/www/_vhost_id_
worker_processes integer
Number of Nginx processes
Default: 4