From ddcc8dfd98f4c40ba4c105e8e24d615e55aeef68 Mon Sep 17 00:00:00 2001
From: elijah <elijah@riseup.net>
Date: Wed, 16 Feb 2022 10:35:01 -0800
Subject: [PATCH] updated README
---
README.rst | 38 +++++++++++++++++++++++++++++++++++---
1 file changed, 35 insertions(+), 3 deletions(-)
diff --git a/README.rst b/README.rst
index e7e81ea..664e38f 100644
--- a/README.rst
+++ b/README.rst
@@ -6,7 +6,7 @@ Menshen is a geolocation and gateway status service for LEAP VPN.
In chinese folk religions, `menshen <https://en.wikipedia.org/wiki/Menshen>`_
are guardians of doors and gates.
-The geolocation service provides the remote ip (via X-Forwarded-For header, if
+The geolocation service provides the remote IP (via X-Forwarded-For header, if
present), country code, city, and geographical coordinates. Information is
provided in plain text format, under ``/``, and in json, under ``/json``.
@@ -20,14 +20,17 @@ You can use ``geoipupdate`` to download MaxMind's City database::
sudo apt install geoipupdate
sudo cp /usr/share/doc/geoipupdate/examples/GeoIP.conf.default /etc/GeoIP.conf
+ sudo sed -i 's/YOUR_ACCOUNT_ID_HERE/xxxxxx/' /etc/GeoIP.conf
+ sudo sed -i 's/YOUR_LICENSE_KEY_HERE/xxxxxx/' /etc/GeoIP.conf
sudo geoipupdate -v
-(note: this service now requires a license key)
+Note: downloading the city database requires a free license key.
Usage
-----------------------
+
-api <tld>
- domain for the api. Default: black.riseup.net. It can be also set via MENSHEN_API env var.
+ domain for the api. Default: black.riseup.net. It can be also set via MENSHEN_API env var.
-geodb <path>
path to the GeoLite2-City database (default is "/var/lib/GeoIP/GeoLite2-City.mmdb")
-port <port>
@@ -39,3 +42,32 @@ Usage
-server_key string
path to the key file for TLS
+Running Locally
+-----------------------
+
+There are several options for running menshen locally for development.
+
+As a container from the registry::
+
+ docker pull registry.0xacab.org/leap/menshen
+ docker run -p 9001:9001 -v /var/lib/GeoIP/:/var/lib/GeoIP/ -e "MENSHEN_API=https://api.example.org" registry.0xacab.org/leap/menshen
+
+As a container built locally::
+
+ docker build -t menshen:latest .
+ docker run -p 9001:9001 -v /var/lib/GeoIP/:/var/lib/GeoIP/ -e "MENSHEN_API=https://api.example.org" menshen:latest
+
+Run without container::
+
+ go build
+ ./menshen -notls -api https://api.example.org
+
+Fetch the results::
+
+ curl -H "X-Forwarded-For: 8.8.8.8" localhost:9001/json
+
+See Also
+-----------------------
+
+<https://github.com/weaming/geoip>
+
--
GitLab