w1cdn/spothole
1
0
Fork 0
mirror of https://git.ianrenton.com/ian/spothole.git synced 2026-06-23 21:25:12 +00:00
Code Issues 13 Packages Projects Releases Wiki Activity

Add an API-only mode that hides the server's web UI. Closes #111

Browse Source
This commit is contained in:
Ian Renton
2026-06-09 10:38:16 +01:00
parent cd40cd985d
commit cd30fc765b
17 changed files with 108 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
README.md
View File

@@ -22,9 +22,11 @@ You can access the public version's web interface at [https://spothole.app](http
This is a Progressive Web App, so you can also "install" it to your Android or iOS device by accessing it in Chrome or Safari respectively, and following the menu-driven process for installing PWAs.
You are more than welcome to use the data and the API that Spothole provides to power your own software. There are many ways to do this; see below.
## Embedding Spothole in another website
You can embed Spothole in another website, e.g. for use as part of a ham radio custom dashboard.
You can embed Spothole's web interface in another website, e.g. for use as part of a ham radio custom dashboard.
URL parameters can be used to trigger an "embedded" mode which hides the headers, footers and settings. In this mode, you provide configuration for the various filter and display options via additional URL parameters. Any settings that the user has set for Spothole are ignored. This is so that the embedding site can select, for example, their choice of dark mode or SIG filters, which will not impact how Spothole appears when the user accesses it directly. Effectively, it becomes separate to their normal Spothole settings.
@@ -90,11 +92,9 @@ Then edit `config.yml` in your text editor of choice to set up the software as y
By default, all outdoor programme providers are enabled, as is one cluster node and the NG3K DXpedition data. The RBN spot providers are turned off by default due to the volume of traffic from CW/RTTY/FT8 skimmers, and the APRS and Packet spot providers are off by default on the assumption that Spothole users want a spot with a human at the other end of it, but all can be easily re-enabled.
`config.yml` has some entries for QRZ.com username & password, and Clublog API keys. If provided, these allow Spothole to retrieve more information about DX spots, such as the country their callsign corresponds to. The software will work just fine without them, but you may find a few country flags etc. are less accurate or missing.
Other parameters you will want to update include the base URL to your instance, and whether you want to serve a full web-based DX cluster interface or just the API endpoints for client software to use.
Clublog API keys are free, but you'll need to get your own by submitting a helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by my Spothole server, so unless you change the source code of yours to radically increase the rate of querying Clublog, I'm sure they will be fine with your server too.
Free QRZ.com accounts offer only limited access to the site's data via their API. You'll have to sign up for one of their "XML Data Subscriber" plans to gain access to the full data, but if you're on a free account then the software will get what information it can.
`config.yml` has an entry for a Clublog API key. If provided, this will allow Spothole to retrieve some more information about DX spots. The software will work just fine without it, but you may find a few country flags etc. are less accurate or missing. Clublog API keys are free, but you'll need to get your own by submitting a helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by my Spothole server, so unless you change the source code of yours to radically increase the rate of querying Clublog, I'm sure they will be fine with your server too.
Once you're happy with the content of `config.yml`, you can proceed to running the software.
@@ -246,11 +246,6 @@ To set up nginx as a reverse proxy that sits in front of Spothole, first ensure
Create a file at `/etc/nginx/sites-available/` called `spothole`. Give it the following contents, replacing `spothole.app` 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 too.
```nginx
map $request_uri $cors_origin {
~^/api *;
default "";
}
server {
server_name spothole.app;
@@ -263,7 +258,7 @@ server {
location ~ ^/api/v1/(spots|alerts)/stream {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://127.0.0.1:8081;
proxy_pass http://127.0.0.1:8080;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 24h;
@@ -271,7 +266,7 @@ server {
proxy_send_timeout 24h;
proxy_set_header X-Accel-Buffering no;
proxy_hide_header Access-Control-Allow-Origin;
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Origin * always;
add_header Cache-Control no-store always;
add_header Content-Type text/event-stream always;
}
@@ -280,13 +275,13 @@ server {
location /api/ {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://127.0.0.1:8081;
proxy_pass http://127.0.0.1:8080;
proxy_buffering on;
proxy_cache off;
proxy_read_timeout 30s;
proxy_connect_timeout 10s;
proxy_hide_header Access-Control-Allow-Origin;
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Origin * always;
add_header Cache-Control no-store always;
}
@@ -294,7 +289,7 @@ server {
location / {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://127.0.0.1:8081;
proxy_pass http://127.0.0.1:8080;
proxy_buffering on;
proxy_read_timeout 30s;
proxy_connect_timeout 10s;
@@ -303,11 +298,11 @@ server {
}
```
One further change you might want to make to the file above is the `add_header Access-Control-Allow-Origin` statement. This is what's used on
One further change you might want to make to the file above is the `add_header Access-Control-Allow-Origin` 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 `/api`. If you want
*your* 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 this line. (Note that this doesn't stop other people writing *non-web-based* software that accesses your
you can remove these lines. (Note that this doesn't stop other people writing *non-web-based* software that accesses your
Spothole API—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 *any* software, that's an aspect of nginx or firewall config that you will need
to find help with elsewhere.)

11
config-example.yml
View File

@@ -6,6 +6,14 @@
# this as "N0CALL" and it shouldn't do any harm, as we're not sending anything to the various networks, only receiving.
server-owner-callsign: "N0CALL"
# Port to open the local web server on
web-server-port: 8080
# Run in API-only mode? When enabled, the web UI is not served, only the API endpoints and the OpenAPI documentation
# page. If you are running your own Spothole instance purely to serve client software, and not wanting visitors to
# discover a full web-based cluster UI, enable this flag.
api-only-mode: false
# The base URL at which the software runs.
base-url: "http://localhost:8080"
@@ -192,9 +200,6 @@ solar-condition-providers:
name: "KC2G Propagation Data"
enabled: true
# Port to open the local web server on
web-server-port: 8080
# Maximum time to keep spots and alerts in the system before deleting them. By default, one hour for spots and one week
# for alerts.
max-spot-age-sec: 3600

1
core/config.py
View File

@@ -21,6 +21,7 @@ SERVER_OWNER_CALLSIGN = config["server-owner-callsign"]
WEB_SERVER_PORT = config["web-server-port"]
ALLOW_SPOTTING = config["allow-spotting"]
WEB_UI_OPTIONS = config["web-ui-options"]
API_ONLY_MODE = config.get("api-only-mode", False)
# For ease of config, each spot provider owns its own config about whether it should be enabled by default in the web UI
# but for consistency we provide this to the front-end in web-ui-options because it has no impact outside of the web UI.

5
server/handlers/pagetemplate.py
View File

@@ -3,7 +3,7 @@ from datetime import datetime
import pytz
import tornado
from core.config import ALLOW_SPOTTING, WEB_UI_OPTIONS, BASE_URL
from core.config import ALLOW_SPOTTING, WEB_UI_OPTIONS, BASE_URL, SERVER_OWNER_CALLSIGN
from core.constants import SOFTWARE_VERSION
from core.prometheus_metrics_handler import page_requests_counter
@@ -26,7 +26,8 @@ class PageTemplateHandler(tornado.web.RequestHandler):
page_requests_counter.inc()
# Load named template, and provide variables used in templates
self.render(self._template_name + ".html", software_version=SOFTWARE_VERSION, allow_spotting=ALLOW_SPOTTING,
self.render(self._template_name + ".html", software_version=SOFTWARE_VERSION,
server_owner_callsign=SERVER_OWNER_CALLSIGN, allow_spotting=ALLOW_SPOTTING,
web_ui_options=WEB_UI_OPTIONS, baseurl=BASE_URL, current_path=self.request.path,
has_hamqsl=self._has_hamqsl, has_noaa_forecast=self._has_noaa_forecast,
has_giro_ionosonde=self._has_giro_ionosonde)

38
server/webserver.py
View File

@@ -5,6 +5,8 @@ import os
import tornado
from tornado.web import StaticFileHandler
from core.config import SERVER_OWNER_CALLSIGN, ALLOW_SPOTTING
from core.constants import SOFTWARE_VERSION
from core.utils import empty_queue
from server.handlers.api.addspot import APISpotHandler
from server.handlers.api.dxstats import APIDxStatsHandler
@@ -21,7 +23,7 @@ from server.handlers.pagetemplate import PageTemplateHandler
class WebServer:
"""Provides the public-facing web server."""
def __init__(self, spots, alerts, solar_conditions, status_data, solar_condition_providers, port):
def __init__(self, spots, alerts, solar_conditions, status_data, solar_condition_providers, port, api_only_mode=False):
"""Constructor"""
self._spots = spots
@@ -32,6 +34,7 @@ class WebServer:
self._status_data = status_data
self._solar_condition_providers = solar_condition_providers
self._port = port
self._api_only_mode = api_only_mode
self._shutdown_event = asyncio.Event()
self.web_server_metrics = {
"last_page_access_time": None,
@@ -61,8 +64,8 @@ class WebServer:
page_opts = {"web_server_metrics": self.web_server_metrics, "has_hamqsl": has_hamqsl,
"has_noaa_forecast": has_noaa_forecast, "has_giro_ionosonde": has_giro_ionosonde}
app = tornado.web.Application([
# Routes for API calls
# API endpoints are always enabled
api_routes = [
(r"/api/v1/spots", APISpotsHandler, {"spots": self._spots, "web_server_metrics": self.web_server_metrics}),
(r"/api/v1/alerts", APIAlertsHandler,
{"alerts": self._alerts, "web_server_metrics": self.web_server_metrics}),
@@ -81,21 +84,36 @@ class WebServer:
(r"/api/v1/lookup/sigref", APILookupSIGRefHandler, {"web_server_metrics": self.web_server_metrics}),
(r"/api/v1/lookup/grid", APILookupGridHandler, {"web_server_metrics": self.web_server_metrics}),
(r"/api/v1/spot", APISpotHandler, {"spots": self._spots, "web_server_metrics": self.web_server_metrics}),
# Routes for templated pages
]
# If in API-only mode, serve a basic homepage; in normal mode, serve the usual UI routes
if self._api_only_mode:
logging.info("API-only mode is enabled. Web UI will not be served.")
ui_routes = [
(r"/", PageTemplateHandler, {"template_name": "api_only_home", **page_opts})
]
else:
ui_routes = [
(r"/", PageTemplateHandler, {"template_name": "spots", **page_opts}),
(r"/map", PageTemplateHandler, {"template_name": "map", **page_opts}),
(r"/bands", PageTemplateHandler, {"template_name": "bands", **page_opts}),
(r"/alerts", PageTemplateHandler, {"template_name": "alerts", **page_opts}),
(r"/add-spot", PageTemplateHandler, {"template_name": "add_spot", **page_opts}),
(r"/conditions", PageTemplateHandler, {"template_name": "conditions", **page_opts}),
(r"/status", PageTemplateHandler, {"template_name": "status", **page_opts}),
(r"/about", PageTemplateHandler, {"template_name": "about", **page_opts}),
(r"/about", PageTemplateHandler, {"template_name": "about", **page_opts})
]
# Only allow the Add Spot page if spotting is allowed
if ALLOW_SPOTTING:
ui_routes += [(r"/add-spot", PageTemplateHandler, {"template_name": "add_spot", **page_opts})]
# API docs, Prometheus metrics, and finally static assets are always available regardless of API-only mode.
misc_routes = [
(r"/apidocs", PageTemplateHandler, {"template_name": "apidocs", **page_opts}),
# Route for Prometheus metrics
(r"/metrics", PrometheusMetricsHandler),
# Default route to serve from "webassets"
(r"/(.*)", StaticFileHandler, {"path": os.path.join(os.path.dirname(__file__), "../webassets")}),
],
(r"/(.*)", StaticFileHandler, {"path": os.path.join(os.path.dirname(__file__), "../webassets")})
]
app = tornado.web.Application(api_routes + ui_routes + misc_routes,
template_path=os.path.join(os.path.dirname(__file__), "../templates"),
debug=False)
app.listen(self._port)

5
spothole.py
View File

@@ -9,7 +9,7 @@ from diskcache import Cache
from core.cleanup import CleanupTimer
from data.solar_conditions import SolarConditions
from core.config import config, WEB_SERVER_PORT, SERVER_OWNER_CALLSIGN
from core.config import config, WEB_SERVER_PORT, SERVER_OWNER_CALLSIGN, API_ONLY_MODE
from core.constants import SOFTWARE_NAME, SOFTWARE_VERSION
from core.lookup_helper import lookup_helper
from core.status_reporter import StatusReporter
@@ -100,7 +100,8 @@ if __name__ == '__main__':
# Set up web server
web_server = WebServer(spots=spots, alerts=alerts, solar_conditions=solar_conditions, status_data=status_data,
solar_condition_providers=solar_condition_providers, port=WEB_SERVER_PORT)
solar_condition_providers=solar_condition_providers, port=WEB_SERVER_PORT,
api_only_mode=API_ONLY_MODE)
# Fetch, set up and start spot providers
for entry in config["spot-providers"]:

2
templates/about.html
View File

@@ -69,7 +69,7 @@
<p>This software is dedicated to the memory of Tom G1PJB, SK, a friend and colleague who sadly passed away around the time I started writing it in Autumn 2025. I was looking forward to showing it to you when it was done.</p>
</div>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script>$(document).ready(function() { $("#nav-link-about").addClass("active"); }); <!-- highlight active page in nav --></script>
{% end %}

4
templates/add_spot.html
View File

@@ -69,8 +69,8 @@
</div>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/add-spot.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/add-spot.js?v=1780997896"></script>
<script>$(document).ready(function() { $("#nav-link-add-spot").addClass("active"); }); <!-- highlight active page in nav --></script>
{% end %}

4
templates/alerts.html
View File

@@ -70,8 +70,8 @@
</div>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/alerts.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/alerts.js?v=1780997896"></script>
<script>$(document).ready(function() { $("#nav-link-alerts").addClass("active"); }); <!-- highlight active page in nav --></script>
{% end %}

23
templates/api_only_home.html Normal file
View File

@@ -0,0 +1,23 @@
{% extends "skeleton.html" %}
{% block head_extra %}
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
{% end %}
{% block body %}
<div class="container mt-5">
<div class="row justify-content-center">
<div class="col-md-8">
<div class="text-center mb-4">
<img src="/img/logo.png" width="192" height="60" alt="Spothole">
</div>
<div class="card">
<div class="card-body">
<p class="card-text">This server is running <strong>Spothole v{{software_version}}</strong>, and is operated by <strong>{{server_owner_callsign}}</strong>.</p>
<p class="card-text">The web UI is not available on this instance because the server is running in API-only mode, intended for use by client software rather than visitors to the website. See the <a href="/apidocs">API documentation</a> for details of how client software can interact with the server.</p>
<p class="card-text">Please see the <a href="https://git.ianrenton.com/ian/spothole#readme">README</a> for details of what Spothole is and how you can run it for yourself.</p>
</div>
</div>
</div>
</div>
</div>
{% end %}

6
templates/bands.html
View File

@@ -76,9 +76,9 @@
<script>
let spotProvidersEnabledByDefault = {% raw json_encode(web_ui_options["spot-providers-enabled-by-default"]) %};
</script>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/spotsbandsandmap.js?v=1780991812"></script>
<script src="/js/bands.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/spotsbandsandmap.js?v=1780997896"></script>
<script src="/js/bands.js?v=1780997896"></script>
<script>$(document).ready(function() { $("#nav-link-bands").addClass("active"); }); <!-- highlight active page in nav --></script>
{% end %}

8
templates/base.html
View File

@@ -1,6 +1,6 @@
{% extends "skeleton.html" %}
{% block head_extra %}
<link rel="stylesheet" href="/css/style.css?v=1780991812" type="text/css">
<link rel="stylesheet" href="/css/style.css?v=1780997896" type="text/css">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<link href="/fa/css/fontawesome.min.css" rel="stylesheet" />
@@ -19,9 +19,9 @@
integrity="sha384-L1eE4eD41kpBIWe2I0eHy+GnEUC4RIpcvibVW2JCminuPlTl+2Bc528iPdVMg5Dn"
crossorigin="anonymous"></script>
<script src="https://misc.ianrenton.com/jsutils/utils.js?v=1780991812"></script>
<script src="https://misc.ianrenton.com/jsutils/ui-ham.js?v=1780991812"></script>
<script src="https://misc.ianrenton.com/jsutils/geo.js?v=1780991812"></script>
<script src="https://misc.ianrenton.com/jsutils/utils.js?v=1780997896"></script>
<script src="https://misc.ianrenton.com/jsutils/ui-ham.js?v=1780997896"></script>
<script src="https://misc.ianrenton.com/jsutils/geo.js?v=1780997896"></script>
{% end %}
{% block body %}
<div class="container">

4
templates/conditions.html
View File

@@ -271,8 +271,8 @@
</div>
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.9/dist/chart.umd.min.js"></script>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/conditions.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/conditions.js?v=1780997896"></script>
<script>$(document).ready(function () {
$("#nav-link-conditions").addClass("active");
}); <!-- highlight active page in nav --></script>

6
templates/map.html
View File

@@ -94,9 +94,9 @@
<script>
let spotProvidersEnabledByDefault = {% raw json_encode(web_ui_options["spot-providers-enabled-by-default"]) %};
</script>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/spotsbandsandmap.js?v=1780991812"></script>
<script src="/js/map.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/spotsbandsandmap.js?v=1780997896"></script>
<script src="/js/map.js?v=1780997896"></script>
<script>$(document).ready(function() { $("#nav-link-map").addClass("active"); }); <!-- highlight active page in nav --></script>
{% end %}

6
templates/spots.html
View File

@@ -104,9 +104,9 @@
<script>
let spotProvidersEnabledByDefault = {% raw json_encode(web_ui_options["spot-providers-enabled-by-default"]) %};
</script>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/spotsbandsandmap.js?v=1780991812"></script>
<script src="/js/spots.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/spotsbandsandmap.js?v=1780997896"></script>
<script src="/js/spots.js?v=1780997896"></script>
<script>$(document).ready(function() { $("#nav-link-spots").addClass("active"); }); <!-- highlight active page in nav --></script>
{% end %}

4
templates/status.html
View File

@@ -59,8 +59,8 @@
</div>
</div>
<script src="/js/common.js?v=1780991812"></script>
<script src="/js/status.js?v=1780991812"></script>
<script src="/js/common.js?v=1780997896"></script>
<script src="/js/status.js?v=1780997896"></script>
<script>
$(document).ready(function() { $("#nav-link-status").addClass("active"); }); <!-- highlight active page in nav -->
</script>

2
webassets/apidocs/openapi.yml
View File

@@ -11,6 +11,8 @@ info:
Please note that the data coming out of Spothole is only as good as the data going in. People mis-hear and make typos when spotting callsigns all the time, and there are plenty of areas where Spothole's location data may be inaccurate. If you are doing something where accuracy is important, such as contesting, you should not rely on Spothole's data to fill in any gaps in your log.
Spothole's source code is located at https://git.ianrenton.com/ian/spothole and the README there provides setup instructions if you would like to run your own copy. A demonstration server of Spothole is located at https://spothole.app.
## Changelog
### 1.3