spothole/templates/help/usage/nginx.html

{% extends "../help_page.html" %}
{% block help_content %}

<h2 class="mt-4 mb-4">nginx Reverse Proxy Configuration</h2>
<p>Web servers generally serve their pages from port 80. However, it's best not to serve Spothole's web interface
    directly on port 80, as that requires root privileges on a Linux system. It also and prevents us using HTTPS to
    serve a secure site, since Spothole itself doesn't directly support acting as an HTTPS server. The normal solution
    to this is to use a "reverse proxy" setup, where a general web server handles HTTP and HTTP requests (to port 80
    &amp; 443 respectively), then passes on the request to the back-end application (in this case Spothole). nginx is a
    common choice for this general web server.</p>
<p>To set up nginx as a reverse proxy that sits in front of Spothole, first ensure it's installed e.g.
    <code>sudo apt install nginx</code>, and enabled e.g. <code>sudo systemd enable nginx</code>.</p>
<p>Create a file at <code>/etc/nginx/sites-available/</code> called <code>spothole</code>. Give it the following
    contents, replacing <code>spothole.app</code> with the domain name on which you want to run Spothole. If you changed
    the port on which Spothole runs, update that on the "proxy_pass" line, and if you installed Spothole somewhere other
    than <code>/home/spothole/spothole</code>, adjust the alias location for serving static files.</p>
<p>(The latter section, configuring the nginx server to serve static files directly, improves efficiency because it
    saves Spothole itself from serving JS, CSS etc. files. If you can't do this for some reason, e.g. your nginx and
    spothole are on different computers, you can omit the <code>location /static/ {}</code> block.)</p>
<pre><code>server {
    server_name spothole.app;

    # Global proxy settings
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_connect_timeout 10s;
    proxy_buffering on;

    # Pass on IP address and host information to Spothole, in case logging this information is required
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Wellknown area for Lets Encrypt
    location /.well-known/ {
        alias /var/www/html/.well-known/;
    }

    # Load static assets directly from the Spothole static directory
    location /static/ {
        alias /home/spothole/spothole/static/;
        expires 1h;
        add_header Cache-Control "public, max-age=3600, must-revalidate";
    }

    # SSE endpoints
    location ~ ^/api/v\d*/(spots|alerts)/stream/? {
        proxy_pass http://127.0.0.1:8080;

        # Remove buffering, remove caching, add suitable timeouts for SSE API calls
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 24h;
        proxy_send_timeout 24h;
        proxy_set_header X-Accel-Buffering no;
        add_header Cache-Control no-store always;

        # Allow cross-origin requests to API
        proxy_hide_header Access-Control-Allow-Origin;
        add_header Access-Control-Allow-Origin * always;
    }

    # Other API endpoints
    location /api/ {
        proxy_pass http://127.0.0.1:8080;

        # Remove buffering, remove caching, add suitable timeouts for API calls
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 30s;
        add_header Cache-Control no-store always;

        # Allow cross-origin requests to API
        proxy_hide_header Access-Control-Allow-Origin;
        add_header Access-Control-Allow-Origin * always;
    }

    # Templated pages
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_read_timeout 30s;
        add_header Cache-Control "no-cache, must-revalidate" always;
    }
}
</code></pre>
<p>One further change you might want to make to the file above is the <code>add_header
    Access-Control-Allow-Origin</code> statements. These are what's used on my own Spothole server to make sure that
    other third-party web-based software can get the data from my instance, and applies to any endpoint underneath
    <code>/api</code>. If you want <em>your</em> Spothole instance to be set up the same way, so that others can write
    software in JavaScript that can access it, leave this intact. But if you want your Spothole instance to only be
    usable by scripts running on the web server you write, you can remove these lines. (Note that this doesn't stop
    other people writing <em>non-web-based</em> software that accesses your Spothole API&mdash;the enforcement of
    cross-origin headers only happens within the user's browser. If you need to lock your instance down so that no-one
    else can access it with <em>any</em> software, that's an aspect of nginx or firewall config that you will need to
    find help with elsewhere.)</p>
<p>Now, make a symbolic link to enable the site:</p>
<pre><code>cd /etc/nginx/sites-enabled
sudo ln -sf ../sites-available/spothole
</code></pre>
<p>Test that your nginx config isn't broken using <code>nginx -t</code>. If it works, restart nginx with
    <code>sudo systemctl restart nginx</code>.</p>
<p>If you haven't already done so, set up a DNS entry to make sure requests for your domain name end up at the server
    that's running Spothole.</p>
<p>You should now be able to access the web interface by going to the domain from your browser.</p>
<p>Once that's working, <a href="https://certbot.eff.org/instructions?ws=nginx&amp;os=snap">install certbot</a> onto
    your server. Run it as root, and when prompted pick your domain name from the list. After a few seconds, it should
    successfully provision a certificate and modify your nginx config files automatically. You should then be able to
    access the site via HTTPS.
</p>

{% end %}