Understanding the difference between the root and alias directives in Nginx

Nginx is a web server that is good for serving as a reverse proxy server, load balancer or HTTP cache.

One of the most important task in configuring Nginx to proxy HTTP / HTTPS traffic is telling Nginx where to look for files that it needs for serving HTTP / HTTPS requests.

This posts discusses the root and alias directives that we can use in Nginx configuration files for mapping a url from a HTTP request to a file on the server file system.

Where can we use the root directive?

The root directive is typically placed in server and location blocks. Placing a root directive in the server block makes the root directive available to all location blocks within the same server block.

A Nginx configuration example to illustrate how root directive will be applied

The following is a set of configurations for illustrating how the root directive is applied:

server {
    server_name example.com;
    listen 80;

    index index.html;
    root /var/www/example.com;

    location / {
        try_files $uri $uri/ =404;
    }

    location ^~ /images {
        root /var/www/static;
        try_files $uri $uri/ =404;
    }
}

From the configuration above, Nginx will look inside the /var/www/static directory on the server to look for files to serve HTTP requests made to http://example.com/images/logo.png or http://example.com/images/funny-monkey.jpg.

Nginx will look inside the /var/www/example.com directory for files to serve HTTP requests made to http://example.com/contact.html or http://example.com/about/us.html.

What does the root directive tells Nginx?

The root directive tells Nginx to take the request url and append it behind the specified directory.

For example, with the following configuration block:

server {
    server_name example.com;
    listen 80;

    index index.html;
    root /var/www/example.com;

    location / {
        try_files $uri $uri/ =404;
    }

    location ^~ /images {
        root /var/www/static;
        try_files $uri $uri/ =404;
    }
}

Nginx will map the request made to:

• http://example.com/images/logo.png into the file path /var/www/static/images/logo.png.
• http://example.com/contact.html into the file path /var/www/example.com/contact.html
• http://example.com/about/us.html into the file path /var/www/example.com/about/us.html

Where can we use the alias directive?

The alias directive can only be placed in a location block.

Placing a alias directive in a location block overrides the root or alias directive that was applied at a higher scope.

The following is a set of configurations for illustrating how the alias directive is applied:

server {
    server_name example.com;
    listen 80;
 
    index index.html;
    root /var/www/example.com;
 
    location / {
        try_files $uri $uri/ =404;
    }
 
    location ^~ /images {
        alias /var/www/static;
        try_files $uri $uri/ =404;
    }
}

From the configuration above, Nginx will look inside the /var/www/static directory on the server to look for files to serve HTTP requests made to http://example.com/images/logo.png or http://example.com/images/funny-monkey.jpg.

Nginx will look inside the /var/www/example.com directory for files to serve HTTP requests made to http://example.com/contact.html or http://example.com/about/us.html.

Note that the "location /" block take the root directive as there is no root or alias directive contained within the block.

The "location ^~ /images" takes the alias directive and overrides the root directive.

What does the alias directive tells Nginx?

The alias directive tells Nginx to replace what is defined in the location block with the path specified by the alias directive.

For example, with the following configuration block:

server {
    server_name example.com;
    listen 80;

    index index.html;
    root /var/www/example.com;

    location / {
        try_files $uri $uri/ =404;
    }

    location ^~ /images {
        alias /var/www/static;
        try_files $uri $uri/ =404;
    }
}

Nginx will map the request made to:

• http://example.com/images/logo.png into the file path /var/www/static/logo.png.
• http://example.com/images/third-party/facebook-logo.png into the file path /var/www/static/third-party/facebook-logo.png.
• http://example.com/contact.html into the file path /var/www/example.com/contact.html
• http://example.com/about/us.html into the file path /var/www/example.com/about/us.html

Using root directive over alias directive

Nginx documentation on the alias directive suggests that it is better to use root over alias when the location matches the last part of the directive’s value.

For example, if you want to define an alias directive for a location block like the following:

location /images/ {
    alias /data/w3/images/;
}

You should consider defining a root directive for that location block:

location /images/ {
    root /data/w3;
}

Using alias directive over root directive

We use the alias directive when we want requests made to multiple urls to be served by files contained within the same directory on the server file system.

For instance, if we want requests made for /images/* and /css/* to be served from files located in the /var/www/static directory, we can use the following configuration set:

location ^~ /images {
    alias /var/www/static;
    try_files $uri $uri/ =404;
}

location ^~ /css {
    alias /var/www/static;
    try_files $uri $uri/ =404;
}

• Share
• Tweet
• Share
• Save