docs: refactor redirector docs into api docs
This commit is contained in:
parent
73439a8121
commit
c795a70d80
7 changed files with 48 additions and 158 deletions
26
docs/admin/api/config.rst
Normal file
26
docs/admin/api/config.rst
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
==================
|
||||
Configuration File
|
||||
==================
|
||||
|
||||
The application uses a YAML configuration file to specify various settings. The configuration file should follow the YAML syntax and provide values for the following fields:
|
||||
|
||||
- `DEFAULT_REDIRECTOR_DOMAIN`: The default domain name to use for generating short links when no pool-specific redirector domain is provided. If not specified, it defaults to an empty string.
|
||||
- `MIRROR_COUNTRIES`: A list of country codes for which clients should be redirected to a mirror server. If a client's IP address matches one of the specified countries, they will be redirected. If not specified, clients will always be redirected to a mirror server.
|
||||
- `PUBLIC_KEY`: The public API key used for generating short links for anonymous users. If not specified, it defaults to an empty string.
|
||||
- `UPDATE_KEY`: The API key required for updating the application data via the `/updt` endpoint. This key must be provided in the `Authorization` header as a bearer token.
|
||||
- `GEOIP_DATABASE` (optional): The file path to the GeoIP database used for country lookup. If not specified, it defaults to `/usr/share/GeoIP/GeoIP2-Country.mmdb`.
|
||||
|
||||
Example Configuration
|
||||
---------------------
|
||||
|
||||
An example configuration file may look like this:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
DEFAULT_REDIRECTOR_DOMAIN: example.com
|
||||
MIRROR_COUNTRIES:
|
||||
- US
|
||||
- CA
|
||||
- GB
|
||||
PUBLIC_KEY: public_key
|
||||
GEOIP_DATABASE: /path/to/geoip/database.mmdb
|
||||
44
docs/admin/api/index.rst
Normal file
44
docs/admin/api/index.rst
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
=====================
|
||||
Short Link Redirector
|
||||
=====================
|
||||
|
||||
Welcome to the documentation for the *Bypass Censorship's Short Link Redirector* application. This documentation provides detailed information about the features, components, and usage of the application. The Short Link Redirector is a web application that allows users to generate short links and direct mirror links for URLs.
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
The Short Link Redirector application offers the following features:
|
||||
|
||||
- Short Link Generation: Users can generate short links for URLs, making them easier to share and remember.
|
||||
- Direct Mirror Links: Users can generate and discover direct mirror links that are currently live.
|
||||
- Country-based Redirect: The application can redirect users to mirror servers based on their country, improving user experience.
|
||||
- API Key Authentication: Users can authenticate their requests using API keys, enabling access to mirrors in private resource pools.
|
||||
- GeoIP Integration: The application optionally leverages GeoIP data to perform country lookups for IP addresses.
|
||||
|
||||
Components
|
||||
----------
|
||||
|
||||
The Short Link Redirector application consists of the following main components:
|
||||
|
||||
- Flask Web Server: The web server that hosts the application and handles incoming HTTP requests.
|
||||
- SQLAlchemy: The ORM (Object-Relational Mapping) library used for interacting with the database.
|
||||
- GeoIP Database: The MaxMind GeoIP database that provides country information for IP addresses.
|
||||
- Hashids: The library used for encoding and decoding the short link hashes.
|
||||
|
||||
Documentation Structure
|
||||
-----------------------
|
||||
|
||||
This documentation is structured into the following sections:
|
||||
|
||||
1. :doc:`Installation <install>`: Provides instructions for installing and setting up the Short Link Redirector application.
|
||||
2. :doc:`Configuration <config>`: Explains the configuration options and how to customize the application's behavior.
|
||||
|
||||
We recommend reading through the documentation sequentially to gain a comprehensive understanding of the application and its features.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
:hidden:
|
||||
|
||||
install
|
||||
config
|
||||
68
docs/admin/api/install.rst
Normal file
68
docs/admin/api/install.rst
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
The application is intended to be deployed in AWS using the
|
||||
`bc-redirector <https://registry.terraform.io/modules/sr2c/bc-redirector/aws/latest>`_
|
||||
Terraform module.
|
||||
This deployment is not managed through the portal itself but may be managed alongside the
|
||||
IaC that manages the deployment of the portal itself.
|
||||
|
||||
Deployment
|
||||
----------
|
||||
|
||||
The Terraform module takes care of setting up multiple entry-points to the redirector allowing for
|
||||
per-pool redirector domains, and also generating the necessary configuration file for the redirector.
|
||||
Once deployed, the redirector will not require further manual configuration, although the deployed
|
||||
EC2 instance will be accessible via AWS Systems Manager Session Manager if required for debugging.
|
||||
|
||||
The following Terraform configuration shows an example using the module:
|
||||
|
||||
.. code-block::
|
||||
|
||||
module "redirector" {
|
||||
providers = {
|
||||
aws = aws,
|
||||
aws.acm = aws.acm
|
||||
}
|
||||
source = "sr2c/bc-redirector/aws"
|
||||
# TODO: version = "x.x.x"
|
||||
namespace = "eg"
|
||||
name = "redirector"
|
||||
default_redirector_domain = "example.com"
|
||||
|
||||
entry_points = [
|
||||
"example.com",
|
||||
"example.org"
|
||||
]
|
||||
|
||||
public_key = var.public_key
|
||||
secret_key = random_password.secret_key.result
|
||||
update_key = var.update_key
|
||||
|
||||
maxmind_account_id = var.maxmind_account_id
|
||||
maxmind_licence_key = var.maxmind_licence_key
|
||||
}
|
||||
|
||||
The `public_key` must match the API key of the public pool configured within the portal.
|
||||
The `update_key` may must match the "filename" configured for the distribution list below.
|
||||
|
||||
The MaxMind account used will need to have at least a subscription for the GeoIP2 Country
|
||||
database.
|
||||
A subscription for GeoIP2 City will include the GeoIP2 Country database.
|
||||
|
||||
Data Updates
|
||||
------------
|
||||
|
||||
Once deployed, the redirector must learn about the available mirror resources.
|
||||
This requires configuring a :doc:`distribution list <../../user/lists>` inside the portal.
|
||||
|
||||
* **Resource Pool**: any (ignored)
|
||||
* **Provider**: HTTP POST
|
||||
* **Distribution Method**: Redirector Data
|
||||
* **Encoding**: JSON (Plain)
|
||||
* **Description**: <*description of the redirector instance*>
|
||||
* **Container**: \https://<*redirector domain*>/updt
|
||||
* **Git Branch/Region**: na
|
||||
* **Role ARN**: <*blank*>
|
||||
* **Filename**: <*update key*>
|
||||
Loading…
Add table
Add a link
Reference in a new issue