w1cdn/spothole
1
0
Fork 0
mirror of https://git.ianrenton.com/ian/spothole.git synced 2026-09-24 08:14:32 +00:00
Code Issues 13 Packages Projects Releases Wiki Activity

Rationalise docs part 5 #151

Browse Source
This commit is contained in:
Ian Renton
2026-09-23 21:42:22 +01:00
parent 5db79ec85a
commit 981fea57ed
22 changed files with 494 additions and 440 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/help/usage/nginx.html
+32 -29
View File
@@ -1,22 +1,22 @@
{% 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>
<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>
<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;
@@ -84,26 +84,29 @@ on different computers, you can omit the <code>location /static/ {}</code> block
}
}
</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>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>
<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>
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>
<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 %}