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

<h2 class="mt-4 mb-4">Running your own Server</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 the
    main <code>spothole.app</code> server, so unless you change the source code of yours to radically increase the rate
    of querying Clublog, they should be fine with your server too.</p>
<p>If your server is public and allows spots to be submitted, you may want to protect it from bots and spammers by
    setting <code>protect_spot_submission</code> to <code>true</code> and setting the reCAPTCHA keys in
    <code>config.yml</code>. Users of the web interface will then need to solve a CAPTCHA to submit a spot. Third-party
    client software can't do that, so if you want to allow a particular client to submit spots, generate an API key for
    it, add it to the <code>api_keys</code> list in <code>config.yml</code>, and send it privately to the client's
    developer. They send it in the <code>X-API-Key</code> header of each request, and Spothole will accept their spots.
    To revoke a key, remove it from the list and restart Spothole. If <code>protect_spot_submission</code> is
    <code>false</code>, anyone can submit spots and API keys aren't needed.</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 %}