[part 1] Stylish modern "autoindex" in Angie/nginx without sms and third-party modules

Auto-index is the functionality of an HTTP server that allows you to automatically display a list of files contained in it when accessing a directory to the file system. I was surprised that someone uses an outdated module, because back in 2014, I added support for JSON and XML formats to the naginx-built naginx module, which makes third-party solutions redundant. Why it took a third-party module mentioned in the matter - it is quite understandable, because the appearance of the page with the list of files by default looks very ascetic, so I want to decorate it and improve. And how to do it elegantly and simply without additional modules, I will demonstrate clearly on ready-made examples. I will show at Angie, but all this is also applicable to nginx, although continuing to use it today instead of Angie is no sense, and rather even harmful. In addition, in Angie version 1.1.0, the autoindex module has been further refined and now provides a “natural” sorting, the result of which looks more logical. The problem that this solves can be clearly seen in the listing of tarbols on the official website of the nginx itself: Sorting curve in nginx by https://nginx.org/download/ After nginx-0.1.1.tar.gz goes immediately nginx-0.1.10.tar.gz and so on to the version nginx-0.1.19.t.gz, where the unexpected inclusion of nginx-0.1.2.t.r.gz again appears; the obvious disorder, which leads to a "dumb" symbolic comparison of lines using strcp(). And here's what the same listing looks like in Angie: "Natural" sorting in Angie Here to demonstrate I had to create a pack of empty files. I would show on a live example, but we will get to the two-digit versions only in six months (but already in advance everything was provided!). In fact, there are still many such small, at first glance, imperceptible processing in Angie in a variety of aspects. Ways to improve the auto-index So, first, let’s go through all the main ways to improve the auto-index, which can meet and were used at different times even in nginx, discuss their pros and cons. sub- and filters The way is that with the help of the built-in modules (directives) sub_filter) the body of the answer changes and CSS-style CSS-swalls are added to the standard HTML output with a listing, possibly JS-scripts, and, if necessary, the markup structure may change. Once it was the simplest and most trivial solution that allowed to improve the built-in autoindex without third-party modules, but today there are ways much better, so we will not dwell on it in detail. It's obvious. "Fancy Index" and other third-party modules The essence of such a module is that many new directives are added to configure in every way how the output HTML will look: add styles, change the date format, etc. The main problem is the need to install a third-party module. And it is good if it is already in the recast, but it is also possible that in the official repositories on the nginx website it is not; then the module needs to be assembled independently. In addition, the quality of third-party modules usually does not reach the quality of native modules, and you can face unexpected errors and even vulnerabilities. And there is also a risk that at some point the module will be incompatible with the latest version and there will be no one to quickly fix it, because the last (at the moment) the change in the repository ngx_fancyindex was two years ago. The main author seems to have abandoned the development. At the same time, in its capabilities, this method, in general, is not far from the previous version. XML + XSLT Customize autoindex_format xml;and native autoindex begins to issue a list of directories in XML format. This further allows you to easily convert data into almost any desired form on the side of the server itself or even the client. The most interesting transformation with the built-in XSLT filter: location / { autoindex on; autoindex_format xml; xslt_stylesheet /path/to/template.xslt; } XSLT templates are a very convenient way to work with XML. You can create your own template, or you can find ready and get a colorful HTML page on the output. We will look at some of these. Of the disadvantages of using the XSLT filter on the side of the web server, you can note a slightly greater load on the processor and additional dependence on the libxml2/libxslt. And from the advantages here is that at the output you can get ready HTML absolutely any desired kind, which does not require additional processing from the client, and therefore the method will work even with the JavaScript disabled. And it is not necessary to convert the index to HTML. You can in any other format, such as CV, or even display a listing in the form of a textual ASCII art when querying a curl-subitte from the console - after all, in your hands all the power of XSLT-stuponization. JSON(P) + JavaScript As in the previous case, but this time we indicate autoindex_format json;

Apr 21, 2025 - 13:57

[part 1] Stylish modern "autoindex" in Angie/nginx without sms and third-party modules

Auto-index is the functionality of an HTTP server that allows you to automatically display a list of files contained in it when accessing a directory to the file system.

I was surprised that someone uses an outdated module, because back in 2014, I added support for JSON and XML formats to the naginx-built naginx module, which makes third-party solutions redundant.

Why it took a third-party module mentioned in the matter - it is quite understandable, because the appearance of the page with the list of files by default looks very ascetic, so I want to decorate it and improve. And how to do it elegantly and simply without additional modules, I will demonstrate clearly on ready-made examples.

I will show at Angie, but all this is also applicable to nginx, although continuing to use it today instead of Angie is no sense, and rather even harmful.

In addition, in Angie version 1.1.0, the autoindex module has been further refined and now provides a “natural” sorting, the result of which looks more logical. The problem that this solves can be clearly seen in the listing of tarbols on the official website of the nginx itself:

Sorting curve in nginx by https://nginx.org/download/

After nginx-0.1.1.tar.gz goes immediately nginx-0.1.10.tar.gz and so on to the version nginx-0.1.19.t.gz, where the unexpected inclusion of nginx-0.1.2.t.r.gz again appears; the obvious disorder, which leads to a "dumb" symbolic comparison of lines using strcp().

And here's what the same listing looks like in Angie:

"Natural" sorting in Angie

Here to demonstrate I had to create a pack of empty files. I would show on a live example, but we will get to the two-digit versions only in six months (but already in advance everything was provided!). In fact, there are still many such small, at first glance, imperceptible processing in Angie in a variety of aspects.

Ways to improve the auto-index
So, first, let’s go through all the main ways to improve the auto-index, which can meet and were used at different times even in nginx, discuss their pros and cons.

sub- and filters

The way is that with the help of the built-in modules (directives) sub_filter) the body of the answer changes and CSS-style CSS-swalls are added to the standard HTML output with a listing, possibly JS-scripts, and, if necessary, the markup structure may change.

Once it was the simplest and most trivial solution that allowed to improve the built-in autoindex without third-party modules, but today there are ways much better, so we will not dwell on it in detail. It's obvious.

"Fancy Index" and other third-party modules The essence of such a module is that many new directives are added to configure in every way how the output HTML will look: add styles, change the date format, etc.

The main problem is the need to install a third-party module. And it is good if it is already in the recast, but it is also possible that in the official repositories on the nginx website it is not; then the module needs to be assembled independently. In addition, the quality of third-party modules usually does not reach the quality of native modules, and you can face unexpected errors and even vulnerabilities.

And there is also a risk that at some point the module will be incompatible with the latest version and there will be no one to quickly fix it, because the last (at the moment) the change in the repository ngx_fancyindex was two years ago. The main author seems to have abandoned the development. At the same time, in its capabilities, this method, in general, is not far from the previous version.

XML + XSLT

Customize autoindex_format xml;and native autoindex begins to issue a list of directories in XML format. This further allows you to easily convert data into almost any desired form on the side of the server itself or even the client.

The most interesting transformation with the built-in XSLT filter:

location / {
    autoindex on;
    autoindex_format xml;

    xslt_stylesheet /path/to/template.xslt;
}

XSLT templates are a very convenient way to work with XML. You can create your own template, or you can find ready and get a colorful HTML page on the output. We will look at some of these.

Of the disadvantages of using the XSLT filter on the side of the web server, you can note a slightly greater load on the processor and additional dependence on the libxml2/libxslt.

And from the advantages here is that at the output you can get ready HTML absolutely any desired kind, which does not require additional processing from the client, and therefore the method will work even with the JavaScript disabled.

And it is not necessary to convert the index to HTML. You can in any other format, such as CV, or even display a listing in the form of a textual ASCII art when querying a curl-subitte from the console - after all, in your hands all the power of XSLT-stuponization.

JSON(P) + JavaScript

As in the previous case, but this time we indicate autoindex_format json;, or autoindex_format jsonp;and we get a ready-made JSON with all the opportunities due for its further processing.

With the help of a built-in JSON module with JSON, it is easy to work on the server side. But the most practical and interesting option is processing on the client, i.e. in the browser itself.

Using an SSI-filter or SSI template, you can take a directory list in JSON and turn it into an HTML template with a JavaScript function to convert it. And you can simply customize the return of a static HTML page with a JS script that asynchronously requests JSON, and the auto-index will then work as a one-page application. Ready-made solutions will be discussed further.

From the minuses here is that if JavaScript can be turned off or not supported by a client, but nowadays it is a rarity.

In additional advantages, you can write that the data in JSON format is quite compactly packed and perfectly compressed. In the case of a single-page application, the amount of information transmitted to the client during navigation by directory is minimal.

If you also set up WebDAV for all this, then not only navigation by directories on the server, but also manipulation with them will be available.

Ready-made solutions

Now, let’s customize a few ready-made solutions that are easy to find in GitHub.

All actions will be performed on a deb distribution. We collect packages for a huge number of systems, so it will not be difficult to reproduce these steps on any other system. And for the convenience of migrating with nginx, we wrote a simple guide.

For my sake of simplicity, I will use such a basic preparation of the minimum configuration (/etc/angie/angie.conf):

events {}

http {
    server {
        listen  80;

        location /angie/ {
            root /srv/www/public;

            autoindex  on;
        }
    }
}

Launching Angie with her:

service angie start

And by opening a page in the browser to the address link, I can observe the standard output of the auto-index:
Launching Angie with her:

As a directory for which a list of subdirections and files is displayed, the directory was chosen /srv/www/public/angie/on the server I unpacked Angie's source.
Ready-made XSLT templates for XML

First, let’s try ready-made XSLT templates with server-side conversion.

Let's try to include XML's output, for which in our locationAdd the directive autoindex_format xml:

location /angie/ {
    root /srv/www/public;

    autoindex  on;
    autoindex_format  xml;
}

Update the configuration:

service angie reload

Let’s see what the answer will look like:

$ curl http://ayhan-dev.online/angie/


auto
conf
contrib
html
man
src
tests
CHANGES
CHANGES.ru
LICENSE
README
configure

As you can see, the answer is a fairly simple XML document consisting of a root element . Inside it may be elements denoting directories, and elements Describing files. There may also be an element in the case of a different type of object (for example, unix-socket) is present in the file system. These elements contain appropriate file names, directories and other objects. They all have an attribute mtimecontaining the modification time in ISO 8601 format, and the elements additionally present attribute size, containing the file size in bytes.

Next, install a dynamic xslt module:

# apt install angie-module-xslt
...
Unpacking angie-module-xslt (1.8.2-1~noble) ...
Setting up angie-module-xslt (1.8.2-1~noble) ...
----------------------------------------------------------------------

The XSLT dynamic module for Angie has been installed.
To enable this module, add the following to /etc/angie/angie.conf
and reload angie:

    load_module modules/ngx_http_xslt_filter_module.so;

Please refer to the modules documentation for further details:
https://en.angie.software/angie/docs/configuration/modules/http/http_xslt/

The module during the installation itself suggests that you need to register in the configuration for downloading it. So we will do: add this line to the main configuration section:

events {}

load_module  modules/ngx_http_xslt_filter_module.so;

http {
    ...
}

This is the final preparations, let's try.
EvilVir/Nginx-Autoindex

Repository: https://github.com/EvilVir/Nginx-Autoindex

First of all, download XSLT-template autoindex.xslt:

$ cd /srv/www
$ wget https://raw.githubusercontent.com/EvilVir/Nginx-Autoindex/refs/heads/master/autoindex.xslt

And prescribe it in the settings locationthrough the directive xslt_stylesheetIn this way:

location /angie/ {
     root /srv/www/public;

     autoindex  on;
     autoindex_format  xml;

     xslt_stylesheet /srv/www/autoindex.xslt;
}

Please note that my template file is outside the public root directory of the web server specified in root.

Do not forget to restart the configuration:

service angie reload

To make sure that everything went well, check:

# service angie status
● angie.service - Angie - high performance web server
     Loaded: loaded (/usr/lib/systemd/system/angie.service; enabled; preset: enabled)
     Active: active (running) since Thu 2025-03-13 09:53:51 MSK; 5min ago
       Docs: https://en.angie.software/angie/docs/
    Process: 1107393 ExecStart=/usr/sbin/angie -c /etc/angie/angie.conf (code=exited, status=0/SUCCESS)
    Process: 1108004 ExecReload=/bin/sh -c /bin/kill -s HUP $(/bin/cat /run/angie.pid) (code=exited, status=0/SUCCESS)
   Main PID: 1107395 (angie)
      Tasks: 6 (limit: 4451)
     Memory: 144.1M (peak: 230.1M)
        CPU: 2.414s
     CGroup: /system.slice/angie.service
             ├─1107395 "angie: master process v1.8.2 #3 [/usr/sbin/angie -c /etc/angie/angie.conf]"
             ├─1107695 "angie: worker process is shutting down #2"
             ├─1108008 "angie: worker process #3"
             ├─1108009 "angie: worker process #3"
             ├─1108010 "angie: worker process #3"
             └─1108011 "angie: worker process #3"

...

As you can see, the generation of configuration changed from #2 to #3 (then this was already the 2nd reload), then it worked out.

This is one of the many differences from nginx in terms of use: Angie in process names you can see the number of the generation, which increases by one with each successful configuration reboot, and the version of the web server is additionally displayed in the name of the master process. In addition, you can display a list of modules using commands angie -mand angie -M.

If the number of the generation has not changed or there was another problem, then it is worth looking at the error log:

cat /var/log/angie/error.log

But we're fine: you can open linkin the browser and see what happened:

The topic is quite simple, it is well suited for those who love dark unobtrusive tones. Of the amenities here there are "bread crumbs", which can be moved on to several directories down:

This template also supports downloading and deleting files through WebDAV. So, let's try to expand our configuration:

location /angie/ {
     root /srv/www/public/;

     autoindex  on;
     autoindex_format  xml;

     xslt_stylesheet /srv/www/autoindex.xslt;     

     dav_methods  PUT;
     client_max_body_size  10M;
}

Here we additionally allowed WebDAV-requests for adding files using the method PUT, as well as through the directive client_max_body_sizeincreased the query body size limit to 10 MB to be able to upload larger files than set by default (1 MB).

For simplicity, setting up a restriction of access will be left outside the framework of this article. Here it is enough to note its obvious need in case of public access to the server.

Create a directory to download files:

$ cd /srv/www/public/anige/
$ mkdir upload

So that work processes can write in it, assign to her the user and the group from which they work:

chown angie:angie upload

Reboot the configuration and check that the configuration generation number has changed again:

# service angie reload
# service angie status
● angie.service - Angie - high performance web server
...
     CGroup: /system.slice/angie.service
             ├─1107395 "angie: master process v1.8.2 #4 [/usr/sbin/angie -c /etc/angie/angie.conf]"
             ├─1108008 "angie: worker process is shutting down #3"
             ├─1108011 "angie: worker process is shutting down #3"
             ├─1108244 "angie: worker process #4"
             ├─1108245 "angie: worker process #4"
             ├─1108246 "angie: worker process #4"
             └─1108247 "angie: worker process #4"

...

If this had not happened, the reason would necessarily have been in the log:

cat /var/log/angie/error.log

For the sake of an example, open our directory in the browser upload(http://ayhan-dev.online/angie/upload/) and try to drag the mouse there tarbol with the sources of Angie:

ooks like it's working! And even the indicator of the loading progress is there.

Still, let’s see that the file was actually uploaded to the directory on the server:

$ ls -l upload
total 1640
-rw------- 1 angie angie 1677058 Mar  9 23:12 angie-1.8.2.tar.gz

The author of the topic gives even more complex examples of settings, including with authorization.

In addition, this topic also has a fork: https://github.com/ViRb3/serve-zip. It is added a button to download the contents of the directory in the form of a single ZIP archive by proxying the request for an additional HTTP service on Go:
Download the directory in the form of a ZIP archive in ViRb3/serve-zip

By the way, you can see the topic live here: https://download.angie.software/

And we move on to the next topic of registration.
gibatronic/ngx-superbindex

Repository: https://github.com/gibatronic/ngx-superbindex

Principle is the same, download XSLT-template superbindex.xslt:

$ cd /srv/www
$ wget https://github.com/gibatronic/ngx-superbindex/releases/download/v2.0.1/superbindex.xslt

And we point it out in our configuration:

location / {
     root /srv/www/public/;

     autoindex  on;
     autoindex_format  xml;

     xslt_stylesheet /srv/www/superbindex.xslt;
}

Reload the configuration again:

service angie reload

And make sure that everything was successful:

# service angie status
● angie.service - Angie - high performance web server
...
     CGroup: /system.slice/angie.service
             ├─1107395 "angie: master process v1.8.2 #5 [/usr/sbin/angie -c /etc/angie/angie.conf]"
             ├─1108247 "angie: worker process is shutting down #4"
             ├─1109361 "angie: worker process #5"
             ├─1109362 "angie: worker process #5"
             ├─1109363 "angie: worker process #5"
             └─1109364 "angie: worker process #5"

...

Otherwise, look at the error in the logger :

cat /var/log/angie/error.log

We are all right, so we update the page in the browser http://ayhan-dev.online/angie/and look at the result:

This is a minimalistic topic with quite unusual capabilities like navigation using a set of file names or directories on the keyboard.

From other features, the color palette settings are stated here, as well as automatic switching between a light and a dark theme depending on the settings of the system.

Let’s move on to the next topic of the design.
Jbox-web/nginx-index-template

Repository: https://github.com/jbox-web/nginx-index-template

Download XSLT-template nginx_template.xslt:

$ cd /srv/www
$ wget https://raw.githubusercontent.com/jbox-web/nginx-index-template/refs/heads/master/nginx_template.xslt

And we prescribe it in the settings:

location / {
     root /srv/www/public/;

     autoindex  on;
     autoindex_format  xml;

     xslt_stylesheet /srv/www/nginx_template.xslt  path='$uri';
}

Continues in the next round.