docs: add github setup

.gitignore

@@ -1,6 +1,5 @@
 # Secrets
 config.yaml
-app/example.db*
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

config.yaml.example

@@ -1,4 +1,8 @@
 ---
+############################################################################
+# Base configuration. All options in this section mandatory.               #
+############################################################################
+
 # Supports any backend supported by SQLAlchemy, but you may need additional
 # packages installed if you're not using SQLite.
 SQLALCHEMY_DATABASE_URI: sqlite:///example.db
@@ -7,27 +11,50 @@ SQLALCHEMY_TRACK_MODIFICATIONS: true
 # You can just put whatever here, but you should change it!
 SECRET_KEY: iechaj0mun6beih3rooga0mei7eo0iwoal1eeweN
 
+# This SSH key must not have a passphrase.
+SSH_PRIVATE_KEY_PATH: /home/bc/.ssh/id_rsa
+SSH_PUBLIC_KEY_PATH: /home/bc/.ssh/id_rsa.pub
+
 # This directory must exist and be writable by the user running the portal.
 TERRAFORM_DIRECTORY: /home/bc/terraform
 
-# AWS (CloudFront)
+############################################################################
-AWS_ACCESS_KEY: accesskeygoeshere
+# Provider configuration follows. You must activate at least one provider. #
-AWS_SECRET_KEY: accesssecretgoeshere
+############################################################################
 
-# Azure
+## Amazon Web Services
-AZURE_RESOURCE_GROUP_NAME: namegoeshere
+#AWS_ACTIVATED: true
-AZURE_STORAGE_ACCOUNT_NAME: namegoeshere
+#AWS_ACCESS_KEY:
-AZURE_LOCATION: westcentralus
+#AWS_SECRET_KEY:
-AZURE_SUBSCRIPTION_ID: subscriptionuuid
-AZURE_TENANT_ID: tenantuuid
-AZURE_CLIENT_ID: clientuuid
-AZURE_CLIENT_SECRET: clientsecretgoeshere
 
-# GitHub
+## Azure
-GITHUB_ORGANIZATION: exampleorg
+#AZURE_ACTIVATED: true
-GITHUB_REPOSITORY: example-repo
+#AZURE_RESOURCE_GROUP_NAME:
-GITHUB_API_KEY: keygoeshere
+#AZURE_STORAGE_ACCOUNT_NAME:
-GITHUB_FILE_V2: mirrorSites.json
+#AZURE_LOCATION:
+#AZURE_SUBSCRIPTION_ID:
+#AZURE_TENANT_ID:
+#AZURE_CLIENT_ID:
+#AZURE_CLIENT_SECRET:
 
-# Hetzner Cloud
+## Fastly
-HCLOUD_TOKEN: tokengoeshere
+#FASTLY_ACTIVATED: true
+#FASTLY_API_KEY:
+
+## GitHub
+#GITHUB_ACTIVATED: true
+#GITHUB_API_KEY:
+
+## Hetzner Cloud
+#HCLOUD_ACTIVATED: true
+#HCLOUD_TOKEN:
+
+## OVH Cloud
+#OVH_ACTIVATED: true
+#OVH_CLOUD_APPLICATION_KEY:
+#OVH_CLOUD_APPLICATION_SECRET:
+#OVH_CLOUD_CONSUMER_KEY:
+#OVH_CLOUD_PROJECT_SERVICE:
+#OVH_OPENSTACK_USER:
+#OVH_OPENSTACK_PASSWORD:
+#OVH_OPENSTACK_TENANT_ID:

docs/admin/conf.rst

@@ -1,6 +1,13 @@
 Configuration File
 ==================
 
-A file named ``config.yaml`` must exist. For each provider in use, credentials must be added.
+A file named ``config.yaml`` must exist. For specifics about the provider configurations, see
+:doc:`External Services <external>`.
+
+Base Configuration
+------------------
+
+Template
+--------
 
 .. literalinclude:: ../../config.yaml.example

docs/admin/external.rst

@@ -0,0 +1,50 @@
+External Services
+=================
+
+Overview
+--------
+
+In order to deploy the circumvention resources, the following providers can be used:
+
++------------+-----+-------+---------+----------------+-----+
+| Resource   | AWS | Azure | Hetzner | GandiCloud VPS | OVH |
++============+=====+=======+=========+================+=====+
+| Web Proxy  | ✅  | ✅    | ❌      | ❌             | ❌  |
++------------+-----+-------+---------+----------------+-----+
+| Tor Bridge | ✅  | ❌    | ✅      | ✅             | ✅  |
++------------+-----+-------+---------+----------------+-----+
+
+Circumvention resource lists can be distributed via:
+
+* AWS S3
+* GitHub
+* GitLab
+
+GitHub
+------
+
+To configure GitHub, you will need a "personal access token".
+It is not possible to restrict a token to specific repositories, so it is best
+to create a
+`machine user <https://docs.github.com/en/developers/overview/managing-deploy-keys#machine-users>`_
+and then invite that user to only the repositories that should be accessed to
+limit the impact of a token disclosure.
+
+To create a token, visit the `New personal access token <https://github.com/settings/tokens/new>`_
+page of the GitHub settings.
+Add a note so that you will be reminded of the purpose of this token when you go to look at it later.
+The expiry can be set according to your threat model.
+GitHub will
+`send an email warning <https://github.blog/changelog/2021-07-26-expiration-options-for-personal-access-tokens/>`_
+before the token expires allowing you to generate a new token and update your configuration.
+
+Once you've generated your token, you can add it to your ``config.yaml``:
+
+.. code-block:: yaml
+
+   # GitHub
+   GITHUB_ACTIVATED: true
+   GITHUB_API_KEY: ghp_Sha8ShueNgihibai6soo1ojoo4aez0deo3bo
+
+The organisation, repository, filename and formats are all configured via the portal interface under
+:doc:`mirror lists <../user/lists>`.

docs/admin/index.rst

@@ -1,21 +0,0 @@
-Application Overview
-====================
-
-External Services
------------------
-
-In order to deploy the circumvention resources, the following providers can be used:
-
-+------------+-----+-------+---------+----------------+-----+
-| Resource   | AWS | Azure | Hetzner | GandiCloud VPS | OVH |
-+============+=====+=======+=========+================+=====+
-| Web Proxy  | ✅  | ✅    | ❌      | ❌             | ❌  |
-+------------+-----+-------+---------+----------------+-----+
-| Tor Bridge | ✅  | ❌    | ✅      | ✅             | ✅  |
-+------------+-----+-------+---------+----------------+-----+
-
-Circumvention resource lists can be distributed via:
-
-* GitHub
-* GitLab
-* AWS S3

docs/index.rst

@@ -20,8 +20,8 @@ Documentation Home
    :maxdepth: 2
    :caption: Admin Guide:
 
-   admin/index.rst
    admin/conf.rst
+   admin/external.rst
    admin/eotk.rst
 
 .. toctree::