Whatbox Logo
Login for certain variables to be updated with your slot's information

Wiki > Userland Nginx

Setup

Intro

Nginx is a web server that will allow you to host either your own website, or make your files available via HTTP. In the example below, we will display a file listing for the files in your /home/user/files directory, which will be password protected with multiple usernames and passwords that you set.

A random port number between 10000 and 32767 is needed and will be used to access your nginx server once setup is complete. The port number 20792 has automatically been generated and will be used throughout this article, but can be changed if needed.

Main configuration file

  1. Create the nginx config and temp directories. mkdir ~/.config/nginx ~/.config/nginx/includes ~/.config/nginx/tmp
  2. Create the configuration file. touch ~/.config/nginx/nginx.conf
  3. Create the file that errors will be displayed in. touch ~/.config/nginx/error.log
  4. Create the file that will log the information about those who access your webserver. touch ~/.config/nginx/access.log
  5. Copy the contents of the box below into the nginx.conf file. nano ~/.config/nginx/nginx.conf

nginx.conf

error_log /home/user/.config/nginx/error.log info;
pid /dev/null;
events { worker_connections 128; }
http {
        include mimes.conf; #for custom file types
        default_type application/octet-stream;
        access_log /home/user/.config/nginx/access.log combined;

        client_body_temp_path /home/user/.config/nginx/tmp/client_body;
        proxy_temp_path /home/user/.config/nginx/tmp/proxy;
        fastcgi_temp_path /home/user/.config/nginx/tmp/fastcgi;
        uwsgi_temp_path /home/user/.config/nginx/tmp/uwsgi;
        scgi_temp_path /home/user/.config/nginx/tmp/scgi;

        server_tokens off;
        sendfile on;
        tcp_nopush on;
        tcp_nodelay on;
        keepalive_timeout 4;

        output_buffers   1 32k;
        postpone_output  1460;

        server {
                listen 20792 default; #IPv4
                listen [::]:20792 default; #IPv6
                autoindex on; #this is the file list
                index index.php index.html;
                
                # path you want to share
                root /home/user/files/;
                
                # file with user:pass info
                auth_basic_user_file /home/user/.config/nginx/htpasswd.conf;
                auth_basic "Personal file server";
                
                # Any extra configuration
                include /home/user/.config/nginx/includes/*.conf;
        }
}

File extension support

  1. Create the file that will provide support for different file extensions. touch ~/.config/nginx/mimes.conf
  2. Copy the contents of the box below into the newly created mimes.conf file. nano ~/.config/nginx/mimes.conf

Mimes.conf

types {
    text/html                             html htm shtml;
    text/css                              css;
    text/xml                              xml;
    image/gif                             gif;
    image/jpeg                            jpeg jpg;
    application/x-javascript              js;
    application/atom+xml                  atom;
    application/rss+xml                   rss;

    font/opentype             otf;

    text/mathml                           mml;
    text/plain                            txt;
    text/vnd.sun.j2me.app-descriptor      jad;
    text/vnd.wap.wml                      wml;
    text/x-component                      htc;

    image/png                             png;
    image/tiff                            tif tiff;
    image/vnd.wap.wbmp                    wbmp;
    image/x-icon                          ico;
    image/x-jng                           jng;
    image/x-ms-bmp                        bmp;
    image/svg+xml                         svg;

    application/java-archive              jar war ear;
    application/mac-binhex40              hqx;
    application/msword                    doc;
    application/pdf                       pdf;
    application/postscript                ps eps ai;
    application/rtf                       rtf;
    application/vnd.ms-excel              xls;
    application/vnd.ms-powerpoint         ppt;
    application/vnd.wap.wmlc              wmlc;
    application/vnd.wap.xhtml+xml         xhtml;
    application/vnd.google-earth.kml+xml  kml;
    application/vnd.google-earth.kmz      kmz;
    application/x-7z-compressed           7z;
    application/x-cocoa                   cco;
    application/x-java-archive-diff       jardiff;
    application/x-java-jnlp-file          jnlp;
    application/x-makeself                run;
    application/x-perl                    pl pm;
    application/x-pilot                   prc pdb;
    application/x-rar-compressed          rar;
    application/x-redhat-package-manager  rpm;
    application/x-sea                     sea;
    application/x-shockwave-flash         swf;
    application/x-stuffit                 sit;
    application/x-tcl                     tcl tk;
    application/x-x509-ca-cert            der pem crt;
    application/x-xpinstall               xpi;
    application/zip                       zip;

    application/octet-stream              bin exe dll;
    application/octet-stream              deb;
    application/octet-stream              dmg;
    application/octet-stream              eot;
    application/octet-stream              iso img;
    application/octet-stream              msi msp msm;

    audio/midi                            mid midi kar;
    audio/mpeg                            mp3;
    audio/x-realaudio                     ra;

    video/3gpp                            3gpp 3gp;
    video/mpeg                            mpeg mpg;
    video/quicktime                       mov;
    video/x-flv                           flv;
    video/x-mng                           mng;
    video/x-ms-asf                        asx asf;
    video/x-ms-wmv                        wmv;
    video/x-msvideo                       avi;
        
    application/x-bittorrent              torrent;
}

Authentication

  1. Create the authentication file. touch ~/.config/nginx/htpasswd.conf

  2. Place authentication information into the file. You can use this command to add a username and password to your htpasswd.conf file. Replace username and password in the command with the username and password you want to add:

     echo 'username:'$(crypt password) >> ~/.config/nginx/htpasswd.conf
    

If you want to manually edit the file, the format is:

    user1:passhash  
    user2:passhash

Replace userN with the username you desire, and passhash with a crypt version of that username's password. (Hashes may be generated using the crypt command: crypt password).

Starting the webserver

  1. Create the file that will start the webserver. touch ~/.config/nginx/start

  2. Make the start file able to be executed. chmod +x ~/.config/nginx/start

  3. Place the contents of the box below into the start file. nano ~/.config/nginx/start

    #!/bin/bash
    # start
    /usr/sbin/nginx -c ~/.config/nginx/nginx.conf &> /dev/null
    

From then on, the server can be started using ~/.config/nginx/start as a command.

Starting the webserver on boot

Add the start command to cron to have nginx automatically start if the server is rebooted. Run crontab -e and add the following line

@reboot ~/.config/nginx/start

Accessing it

You will now be able to access your files folder using the username and password you defined from http://server.whatbox.ca:20792/

Stopping the webserver

Kill the process. pkill -f nginx/nginx.conf

SSL (optional)

To access your webserver securely with SSL you will need to create a self-signed certificate and update nginx.conf.

  1. Create key files. All requested custom information can be left blank. openssl req -new -x509 -nodes -out ~/.config/nginx/server.crt -keyout ~/.config/nginx/server.key
  2. Edit nginx.conf and add the following to the server { block
        listen 20792 ssl; # Replace existing line at start of server{
        listen [::]:20792 ssl; # Replace existing line at start of server{
        
        # ssl on; # this is deprecated by 'listen PORT ssl'
        ssl_certificate /home/user/.config/nginx/server.crt;
        ssl_certificate_key /home/user/.config/nginx/server.key;  

Caveat

The Chrome browser revokes self-signed certificates every time a valid certificate is encountered. This can cause bugs in web applications hosted on your webserver when other tabs have Whatbox pages actively loaded. We recommend using a different browser for your self-signed certificates if this affects you.

PHP (optional)

  1. Create the configuration directory. mkdir ~/.config/php-fpm2

  2. Create the configuration file. touch ~/.config/php-fpm2/conf

  3. Copy the contents below into the configuration file. Be sure to delete any spaces at the start of each line to prevent startup errors. nano ~/.config/php-fpm2/conf

    [global]
    daemonize = yes
    error_log = /home/user/.config/php-fpm2/error.log
        
    [www]
    listen = /home/user/.config/php-fpm2/socket
        
    listen.owner = user
    listen.group = user
    listen.mode = 0600
    
    pm = dynamic
    pm.max_children = 20
    pm.start_servers = 1
    pm.min_spare_servers = 1
    pm.max_spare_servers = 5
    
    php_admin_value[memory_limit] = 4G
    
  4. Start php-fpm: php-fpm --fpm-config ~/.config/php-fpm2/conf

  5. In your nginx configuration directory, create fastcgi_params: touch ~/.config/nginx/fastcgi_params

  6. Copy the contents below into the fastcgi_params file.

    fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
        
    fastcgi_param  QUERY_STRING       $query_string;
    fastcgi_param  REQUEST_METHOD     $request_method;
    fastcgi_param  CONTENT_TYPE       $content_type;
    fastcgi_param  CONTENT_LENGTH     $content_length;
        
    fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
    fastcgi_param  REQUEST_URI        $request_uri;
    fastcgi_param  DOCUMENT_URI       $document_uri;
    fastcgi_param  DOCUMENT_ROOT      $document_root;
    fastcgi_param  SERVER_PROTOCOL    $server_protocol;
        
    fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
    fastcgi_param  SERVER_SOFTWARE    WebServer;
        
    fastcgi_param  REMOTE_ADDR        $remote_addr;
    fastcgi_param  REMOTE_PORT        $remote_port;
    fastcgi_param  SERVER_ADDR        $server_addr;
    fastcgi_param  SERVER_PORT        $server_port;
    fastcgi_param  SERVER_NAME        $server_name;
        
    fastcgi_connect_timeout 60;
    fastcgi_send_timeout 180;
    fastcgi_read_timeout 180;
    fastcgi_buffer_size 128k;
    fastcgi_buffers 8 256k;
    fastcgi_busy_buffers_size 256k;
    fastcgi_temp_file_write_size 256k;
    fastcgi_intercept_errors on;
    
  7. Create the ~/.config/nginx/includes/php.conf file: touch ~/.config/nginx/includes/php.conf and add the following contents to it:

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/home/user/.config/php-fpm2/socket;
    }
    
  8. Restart nginx to reflect the new configuration changes: pkill -f nginx/nginx.conf && ~/.config/nginx/start

WebDAV (optional)

  1. Copy the contents of the box below into the nginx.conf file right below root /home/user/files/. nano ~/.config/nginx/nginx.conf

                    # enable webdav access for shared path
                    dav_methods PUT DELETE MKCOL COPY MOVE;
                    dav_ext_methods PROPFIND OPTIONS;
    
                    create_full_put_path on;
                    dav_access group:rw  all:r;
    
  2. Restart nginx to reflect the new configuration changes: pkill -f nginx/nginx.conf && ~/.config/nginx/start

  3. You can now connect to your WebDAV app using the information in the box below.

         Protocol: WebDAV
         Address: server.whatbox.ca
         Username: (Previously set up username)
         Password: (Previously set up password)
         Port (Advanced): 20792
    

Reverse Proxies

Reverse proxies will allow you to proxy a page so as to allow you to have SSL on an app's web interface that normally wouldn't support SSL. You will need to have setup a self-signed SSL certificate as described above.

        server {
                listen <NewPort> default; #IPv4
                listen [::]:<NewPort> default; #IPv6

                ssl on;
                ssl_certificate /home/user/.config/nginx/server.crt;
                ssl_certificate_key /home/user/.config/nginx/server.key;

                location /
                {
                        proxy_pass  http://server.whatbox.ca:<AppPort>;
                }

        }

Replace <NewPort> with the port you want to access the app on (e.g. https://server.whatbox.ca:<NewPort>). Do not leave the <> symbols.
Replace <AppPort> with the port that your app's web interface already runs on. Do not leave the <> symbols.