Rationalise docs part 4 #151

templates/help/usage/running.html

@@ -0,0 +1,44 @@
+{% extends "../help_page.html" %}
+{% block help_content %}
+
+<h2 class="mt-4 mb-4">Running your own copy</h2>
+<p>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.</p>
+<p>You will require Python version 3.10 or later. If you encounter an error about <code>gdal-config</code> during the following
+process, you will also need <code>libgdal-dev</code> installed.</p>
+<p>To download and set up Spothole on a Debian server, run the following commands. Other operating systems will likely be
+similar.</p>
+<pre><code>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
+</code></pre>
+<p>Then edit <code>config.yml</code> 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.</p>
+<p>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.</p>
+<p>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.</p>
+<p><code>config.yml</code> 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.</p>
+<p>Once you're happy with the content of <code>config.yml</code>, you can proceed to running the software.</p>
+<p>To run the software this time and any future times you want to run it directly from the command line:</p>
+<pre><code>source .venv/bin/activate
+python3 spothole.py
+</code></pre>
+<p>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 <code>You can access your copy of Spothole at
+http://localhost:8080</code> in the log, your server is good to go.</p>
+<p>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.</p>
+
+{% end %}