From 5db79ec85a98ab5518bd7a4b46ec7f56a2d22476 Mon Sep 17 00:00:00 2001 From: Ian Renton Date: Wed, 23 Sep 2026 18:25:05 +0100 Subject: [PATCH] Rationalise docs part 4 #151 --- docs/clients.md | 40 ----- docs/embedding.md | 41 ----- docs/modifying.md | 79 ---------- docs/multicluster.md | 96 ------------ docs/running.md | 54 ------- docs/systemd.md | 34 ----- templates/add_spot.html | 2 +- templates/alerts.html | 2 +- templates/bands.html | 4 +- templates/base.html | 10 +- templates/conditions.html | 2 +- templates/help/index.html | 15 +- templates/help/usage/clients.html | 42 ++++++ .../help/usage/docker.html | 118 +++++++-------- templates/help/usage/embedding.html | 142 ++++++++++++++++++ templates/help/usage/modifying.html | 78 ++++++++++ templates/help/usage/multicluster.html | 82 ++++++++++ .../help/usage/nginx.html | 89 +++++------ templates/help/usage/running.html | 44 ++++++ templates/help/usage/systemd.html | 31 ++++ templates/map.html | 4 +- templates/spots.html | 4 +- templates/status.html | 2 +- webserver/webserver.py | 107 +++++++------ 24 files changed, 604 insertions(+), 518 deletions(-) delete mode 100644 docs/clients.md delete mode 100644 docs/embedding.md delete mode 100644 docs/modifying.md delete mode 100644 docs/multicluster.md delete mode 100644 docs/running.md delete mode 100644 docs/systemd.md create mode 100644 templates/help/usage/clients.html rename docs/docker.md => templates/help/usage/docker.html (60%) create mode 100644 templates/help/usage/embedding.html create mode 100644 templates/help/usage/modifying.html create mode 100644 templates/help/usage/multicluster.html rename docs/nginx.md => templates/help/usage/nginx.html (57%) create mode 100644 templates/help/usage/running.html create mode 100644 templates/help/usage/systemd.html diff --git a/docs/clients.md b/docs/clients.md deleted file mode 100644 index b5fe16f..0000000 --- a/docs/clients.md +++ /dev/null @@ -1,40 +0,0 @@ -## Writing your own client - -One of the key strengths of Spothole is that the API is well-defined and open to anyone to use. This means you can build -your own software that uses data from Spothole. - -As well as the main API endpoints to fetch spots and alerts, with various possible query parameters, there are also -Server-Sent Events (SSE) API endpoints to receive a live feed, plus various utility lookup endpoints for things like -callsign and park data. - -Various approaches exist to writing your own client, but in general: - -* Refer to the API docs. These are built on an OpenAPI definition file (`/static/apidocs/openapi.yml`), which you can - automatically use to generate a client skeleton using various software. -* Call the main "spots" or "alerts" API endpoints to get the data you want. For example, your app could call - `https://spothole.app/api/v2/spots` once every few minutes. Apply filters if necessary. -* Call the "options" API to get an idea of which bands, modes etc. the server knows about. You might want to do that - first before calling the spots/alerts APIs, to allow you to populate your filters correctly. -* Refer to the provided HTML/JS interface for a reference on different approaches. For example, the "alerts"/"upcoming" - page simply query the main spot API on a timer, whereas the spots, map and bands pages combine this approach with - using the Server-Sent Events (SSE) endpoint to update live. -* Let me know if you get stuck, I'm happy to help. - * Caveat: If you have vibe-coded a client, do not contact me until you have read and understood the code using your actual Human Intelligence. - -Please don't hammer the API with an unnecessarily high request rate. For example, Spothole only queries the POTA API -once every two minutes, so if your client is interested in POTA data there's no need to poll Spothole any more often -than that. - -If you absolutely must be informed within seconds of a spot arriving in Spothole, please use the SSE endpoints instead, -e.g. `https://spothole.app/api/v2/spots/stream`. - -If you want to handle different types of spot or alert differently within your client, please consider making a single -request to the Spothole API to retrieve all the data, then filtering on your side. For example, call -`https://spothole.app/api/v2/spots?sig=POTA,SOTA` rather than making two separate calls to -`https://spothole.app/api/v2/spots?sig=POTA` and `https://spothole.app/api/v2/spots?sig=SOTA`. - -Remember, here at Spothole Inc. we offer an industry-standard "five nines" uptime on our server, with our own unique -twist: we don't tell you which side of the decimal point the nines start! (Translation: This is a hobby project. -`spothole.app` runs on the same server as my blog and other stuff. It might go down without warning. By all means base -your own project on data from the main server if you like, but if you want any control over reliability and downtime, -please run your own copy instead.) diff --git a/docs/embedding.md b/docs/embedding.md deleted file mode 100644 index 9278820..0000000 --- a/docs/embedding.md +++ /dev/null @@ -1,41 +0,0 @@ -## Embedding Spothole in another website - -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 activity filters, which will not impact how Spothole appears when the user accesses it directly. Effectively, it -becomes separate to their normal Spothole settings. - -Setting `embedded` to true is important for the rest of the settings to be applied; otherwise, the user's defaults will -be used in preference to the URL params. - -These are supplied with the URL to the page you want to embed, for example for an embedded version of the band map in -dark mode, use `https://spothole.app/bands?embedded=true&dark-mode=true`. For an embedded version of the main spots/home -page in the system light/dark mode, use `https://spothole.app/?embedded=true`. For dark mode showing 70cm TOTA spots -only, use `https://spothole.app/?embedded=true&dark-mode=true&sig=TOTA&band=70cm`. Providing no URL params causes the -page to be loaded in the normal way it would when accessed directly in the user's browser. - -The supported parameters are as follows. Generally these match the equivalent parameters in the real Spothole API, where -a mapping exists. - -| Name | Allowed Values | Default | Example | Description | -|------------------|-------------------------|---------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `embedded` | `true`, `false` | `false` | `?embedded=true` | Enables embedded mode. | -| `color_scheme` | `light`, `dark`, `auto` | `auto` | `?color_scheme=dark` | Forces light or dark mode in preference to the operating system default. | -| `time_zone` | `UTC`, `local` | `UTC` | `?time_zone=local` | Sets times to be in UTC or local time. | -| `limit` | 10, 25, 50, 100 | 50 | `?limit=50` | Sets the number of spots that will be displayed on the main spots page | -| `limit` | 25, 50, 100, 200, 500 | 100 | `?limit=100` | Sets the number of alerts that will be displayed on the alerts page | -| `max_age` | 300, 600, 1800, 3600 | 1800 | `?max_age=1800` | Sets the maximum age of spots displayed on the map and bands pages, in seconds. | -| `band` | Comma-separated list | (all) | `?band=20m,40m` | Sets the list of bands that will be shown on the spots, bands and map pages. Available options match the labels of the buttons in the standard web interface. | -| `sig` | Comma-separated list | (all) | `?sig=POTA,SOTA,NO_SIG` | Sets the list of activities that will be shown on the spots, bands and map pages. Available options match the labels of the buttons in the standard web interface. | -| `source` | Comma-separated list | (all) | `?source=Cluster` | Sets the list of sources that will be shown on any spot or alert pages. Available options match the labels of the buttons in the standard web interface. | -| `mode_type` | Comma-separated list | (all) | `?mode_type=PHONE,CW` | Sets the list of mode types that will be shown on the spots, bands and map pages. Available options match the labels of the buttons in the standard web interface. | -| `dx_continent` | Comma-separated list | (all) | `?dx_continent=NA,SA` | Sets the list of DX Continents that will be shown on any spot or alert pages. Available options match the labels of the buttons in the standard web interface. | -| `de_continent` | Comma-separated list | (all) | `?de_continent=EU` | Sets the list of DE Continents that will be shown on the spots, bands and map pages. Available options match the labels of the buttons in the standard web interface. | -| `map-center-lat` | Numeric (decimal) | (auto) | `?map-center-lat=51.5` | Sets the initial latitude of the map centre on the map page. If omitted, the map auto-fits to the loaded spots. | -| `map-center-lon` | Numeric (decimal) | (auto) | `?map-center-lon=-0.1` | Sets the initial longitude of the map centre on the map page. If omitted, the map auto-fits to the loaded spots. | -| `map-zoom` | Numeric (integer) | (auto) | `?map-zoom=6` | Sets the initial zoom level of the map on the map page. If omitted, the map auto-fits to the loaded spots. | - -See the comment at the end of the next section regarding reliability and uptime of the "main" server. \ No newline at end of file diff --git a/docs/modifying.md b/docs/modifying.md deleted file mode 100644 index 8336215..0000000 --- a/docs/modifying.md +++ /dev/null @@ -1,79 +0,0 @@ -## Modifying the source code - -Spothole is Public Domain licenced, so you can grab the source code and start modifying it for your own needs. -Contributions of code back to the main repository are encouraged, but completely optional. - -### Code structure - -To navigate your way around the source code, this list may help. - -*Python back-end code* - -* `/core` - Core classes and utilities -* `/data` - Data storage classes -* `/providers/spot` - Classes providing spots by accessing the APIs of other services -* `/providers/alert` - Classes providing alerts by accessing the APIs of other services -* `/providers/solarconditions` - Classes providing solar and propagation by accessing the APIs of other services -* `/providers/staticdata` - Classes providing static lookup data by accessing bundled data files or the APIs of other - services -* `/providers/callsign` - Classes providing callsign lookup data by accessing bundled data files or the APIs of other - services -* `/providers/activityrefdata` - Classes providing activity reference lookup data by accessing bundled data files or - the APIs of other services -* `/webserver` - Classes for running Spothole's own web server -* `/telnetserver` - Classes for running Spothole's telnet server -* `spothole.py` - Main application script - -*Templates* - -* `/templates` - Templates used for constructing Spothole's user-targeted HTML pages - -*HTML/JS/CSS front-end code* - -* `/static` - Root for static files served by the web server. These are all served from a path starting `/static/`. -* `/static/apidocs` - Contains the OpenAPI spec (`openapi.yml`) -* `/static/audio` - Audio files used by the web front-end -* `/static/css` - CSS files used by the web front-end -* `/static/img` - image files used by the web front-end -* `/static/js` - JavaScript used by the web front-end -* `/static/vendor` - Third-party libraries (CSS, JS, fonts and images) - -*Miscellaneous* - -* `/` - pip `requirements.txt`, config, README, etc. -* `/docs` - Documentation -* `/images` - Image sources -* `/datafiles` - Local data files, used by some providers when the data will never change and/or is not easily available - online in a format Spothole can handle -* `/cache` - Directory where Spothole stores all the data it uses that should be persisted to disk. Created on first - run. - -### Extending the server - -Spothole is designed to be easily extensible. If you want to write your own spot provider, for example, simply add a -module to the `providers.spot` package containing your class. (Currently, in order to be loaded correctly, the module -(file) name should be the same as the class name, but lower case.) - -Your class should extend "SpotProvider"; if it operates by polling an HTTP Server on a timer, it can instead extend " -HTTPSpotProvider" where some of the work is done for you. - -The class will need to implement a constructor that takes in the `provider_config` and provides it to the superclass -constructor, while also taking any other config parameters it needs. - -If you're extending the base `SpotProvider` class, you will need to implement `start()` and `stop()` methods that start -and stop a separate thread which handles the provider's processing needs. The thread should call `submit()` or -`submit_batch()` when it has one or more spots to report. - -If you're extending the `HTTPSpotProvider` class, you will need to provide a URI to query and an interval to the -superclass constructor. You'll then need to implement the `http_response_to_spots()` method which is called when new -data is retrieved. Your implementation should then call `submit()` or `submit_batch()` when it has one or more spots to -report. - -When constructing spots, use the comments in the Spot class and the existing implementations as an example. All -parameters are optional, but you will at least want to provide a `time` (which must be timezone-aware) and a `dx_call`. - -Finally, simply add the appropriate config to the `spot_providers` section of `config.yml`, and your provider should be -instantiated on startup. - -The same approach as above is also used for alerts, and other types of providers. Give me a shout if you need any -advice. diff --git a/docs/multicluster.md b/docs/multicluster.md deleted file mode 100644 index 79e49d5..0000000 --- a/docs/multicluster.md +++ /dev/null @@ -1,96 +0,0 @@ -## Multiple cluster nodes with different settings - -Dan, S50U has written in with his Spothole cluster settings. He is using a cluster node which provides RBN spots, and -uses different SSIDs on his callsign to get different settings when logged into the same cluster node. For example: - -``` - - - class: "DXCluster" - name: "S50CLX" - enabled: true - host: "s50clx.si" - port: 41112 - login_prompt: "login: " - login_callsign: "callsign-10" -``` - -Telnet to DXSpider and log in with "callsign-10" and execute the following commands: - -`CLEAR/SPOTS ALL` (delete all previous filters)
-`UNSET/ANN` (stop announce messages)
-`UNSET/WCY` (stop wcy messages)
-`UNSET/WWV` (stop wwv messages)
-`SET/DX` (enable human DX spots) - -``` - - - class: "DXCluster" - name: "RBN CW" - enabled: true - host: "s50clx.si" - port: 41112 - login_prompt: "login: " - login_callsign: "callsign-11" - allow_rbn_spots: true - enabled_by_default_in_web_ui: false -``` - -Telnet to DXSpider and log in with "callsign-11" and execute the following commands: - -`CLEAR/SPOTS ALL` (delete all previous filters)
-`UNSET/ANN` (stop announce messages)
-`UNSET/WCY` (stop wcy messages)
-`UNSET/WWV` (stop wwv messages)
-`UNSET/DX` (stop human DX spots)
-`SET/SKIMMER CW` (enable CW RBN spots) - -``` - - - class: "DXCluster" - name: "RBN RTTY" - enabled: true - host: "s50clx.si" - port: 41112 - login_prompt: "login: " - login_callsign: "callsign-12" - allow_rbn_spots: true - enabled_by_default_in_web_ui: false -``` - -Telnet to DXSpider and log in with "callsign-12" and execute the following commands: - -`CLEAR/SPOTS ALL` (delete all previous filters)
-`UNSET/ANN` (stop announce messages)
-`UNSET/WCY` (stop wcy messages)
-`UNSET/WWV` (stop wwv messages)
-`UNSET/DX` (stop human DX spots)
-`SET/SKIMMER RTTY` (enable RTTY RBN spots) - -``` - - - class: "DXCluster" - name: "RBN FT4/8" - enabled: true - host: "s50clx.si" - port: 41112 - login_prompt: "login: " - login_callsign: "callsign-13" - allow_rbn_spots: true - enabled_by_default_in_web_ui: false -``` - -Telnet to DXSpider and log in with "callsign-13" and execute the following commands: - -`CLEAR/SPOTS ALL` (delete all previous filters)
-`UNSET/ANN` (stop announce messages)
-`UNSET/WCY` (stop wcy messages)
-`UNSET/WWV` (stop wwv messages)
-`UNSET/DX` (stop human DX spots)
-`SET/SKIMMER FT` (enable FT RBN spots) - -For each callsign-SSID, we also specify our basic information with commands: - -`SET/NAME Spothole10`, Spothole11... etc.
-`SET/QTH Cerkno`
-`SET/QRA JN66XD`
-`SET/HOME S50CLX` \ No newline at end of file diff --git a/docs/running.md b/docs/running.md deleted file mode 100644 index 9056e05..0000000 --- a/docs/running.md +++ /dev/null @@ -1,54 +0,0 @@ -## Running your own copy - -If you want to run a copy of Spothole with different configuration settings than the main instance, you can download it -and run it on your own local machine or server. - -You will require Python version 3.10 or later. If you encounter an error about `gdal-config` during the following -process, you will also need `libgdal-dev` installed. - -To download and set up Spothole on a Debian server, run the following commands. Other operating systems will likely be -similar. - -```bash -git clone ssh://git@git.ianrenton.com/ian/spothole.git -cd spothole -python3 -m venv ./.venv -source .venv/bin/activate -pip install -r requirements.txt -deactivate -cp config-example.yml config.yml -``` - -Then edit `config.yml` in your text editor of choice to set up the software as you like it. Mostly, this will involve -enabling or disabling the various providers of spot and alert data. - -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. - -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. - -`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. - -To run the software this time and any future times you want to run it directly from the command line: - -```bash -source .venv/bin/activate -python3 spothole.py -``` - -The software can take a few seconds to start up, particularly if it's been run previously and has a large amount of -cache data to sort through. This is normal, don't panic! Once you see `You can access your copy of Spothole at -http://localhost:8080` in the log, your server is good to go. - -If you see some errors on startup, check your configuration, e.g. in case you have specified a port for the web server -that is already in use by something else. diff --git a/docs/systemd.md b/docs/systemd.md deleted file mode 100644 index a4c9189..0000000 --- a/docs/systemd.md +++ /dev/null @@ -1,34 +0,0 @@ -## systemd configuration - -If you want Spothole to run automatically on startup on a Linux distribution that uses `systemd`, follow the -instructions here. For distros that don't use `systemd`, or Windows/OSX/etc., you can find generic instructions for your -OS online. - -Create a file at `/etc/systemd/system/spothole.service`. Give it the following content, adjusting for the user you want -to run it as and the directory in which you have installed it: - -``` -[Unit] -Description=Spothole -After=syslog.target network.target - -[Service] -Type=simple -User=spothole -WorkingDirectory=/home/spothole/spothole -ExecStart=/home/spothole/spothole/.venv/bin/python /home/spothole/spothole/spothole.py --serve-in-foreground -Restart=on-abort - -[Install] -WantedBy=multi-user.target -``` - -Run the following: - -```bash -sudo systemctl daemon-reload -sudo systemctl enable spothole -sudo systemctl start spothole -``` - -Check the service has started up correctly with `sudo journalctl -u spothole -f`. \ No newline at end of file diff --git a/templates/add_spot.html b/templates/add_spot.html index c01a2b1..7cacf17 100644 --- a/templates/add_spot.html +++ b/templates/add_spot.html @@ -77,7 +77,7 @@ - + diff --git a/templates/alerts.html b/templates/alerts.html index e560d9d..5e4cdbf 100644 --- a/templates/alerts.html +++ b/templates/alerts.html @@ -85,7 +85,7 @@ - + diff --git a/templates/bands.html b/templates/bands.html index ec27235..d1402f1 100644 --- a/templates/bands.html +++ b/templates/bands.html @@ -76,8 +76,8 @@ - - + + diff --git a/templates/base.html b/templates/base.html index 3ad1f56..680c970 100644 --- a/templates/base.html +++ b/templates/base.html @@ -1,6 +1,6 @@ {% extends "skeleton.html" %} {% block head_extra %} - + @@ -16,10 +16,10 @@ window.fetchEventSource = fetchEventSource; - - - - + + + + {% end %} {% block body %}
diff --git a/templates/conditions.html b/templates/conditions.html index 66c6982..7e04679 100644 --- a/templates/conditions.html +++ b/templates/conditions.html @@ -284,7 +284,7 @@
- + diff --git a/templates/help/index.html b/templates/help/index.html index 1e792b9..48be834 100644 --- a/templates/help/index.html +++ b/templates/help/index.html @@ -8,7 +8,20 @@

In the sections below, you can find more information about what Spothole is, and how to use it.