diff --git a/README.md b/README.md index bb5ed20..9db2369 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # IP Ask + `whatsmyip` type of web application written in Python with Flask framework [ipask.me](https://ipask.me) --- +
@@ -11,46 +13,51 @@ -* Install Git and Python: +- Install Git and Python: + ``` sudo pacman -S git python ``` -* Clone the git repository: +- Clone the git repository: + ```sh git clone https://github.com/pnedkov/ipask.git cd ipask/ ``` -* Create and activate the Python virtual environment: +- Create and activate the Python virtual environment: + ```sh python -m venv .venv source .venv/bin/activate ``` -* Install the required Python packages: +- Install the required Python packages: + ```sh pip install -r requirements.txt ``` -* (Optional) Download the GeoIP database: +- (Optional) Download the GeoIP database: The GeoIP feature is toggled with the `GEOIP` environment variable which is disabled by default. Enabling `GEOIP` would not do any good if the client's IP address is from a private network. The `GeoLite2-City.mmdb` file is being included in the container - check the `Dockerfile`. Credit: https://github.com/P3TERX/GeoLite.mmdb - * wget: - ``` - wget git.io/GeoLite2-City.mmdb -P resources/ - ``` - * curl: - ``` - curl -L git.io/GeoLite2-City.mmdb -o resources/GeoLite2-City.mmdb - ``` + - wget: + ``` + wget git.io/GeoLite2-City.mmdb -P resources/ + ``` + - curl: + ``` + curl -L git.io/GeoLite2-City.mmdb -o resources/GeoLite2-City.mmdb + ```
--- +
@@ -58,30 +65,32 @@ -* Environment variables: +- Environment variables: | Environment variable | Default value | | --- | --- | | GEOIP | `false` | | REVERSE_DNS_LOOKUP | `false` | -* Run using `run.py`: +- Run using `run.py`: ```sh python run.py ``` Example: + ```sh REVERSE_DNS_LOOKUP=true python run.py ``` - -* Run using `run.sh` (recommended): - + +- Run using `run.sh` (recommended): + This will run the application with the Python WSGI HTTP Server - [gunicorn](https://gunicorn.org): - + ```sh ./run.sh ``` + Gunicorn-specific environment variables: | Environment variable | Default value | | --- | --- | @@ -89,7 +98,8 @@ | [GUNICORN_WORKERS](https://docs.gunicorn.org/en/stable/settings.html#workers) | `CPU Cores * 2 + 1` | | [GUNICORN_THREADS](https://docs.gunicorn.org/en/stable/settings.html#threads) | `1` | - Example: + Example: + ```sh REVERSE_DNS_LOOKUP=true GUNICORN_WORKERS=3 ./run.sh ``` @@ -97,6 +107,7 @@
--- +
@@ -104,7 +115,7 @@ -* Prerequisites: +- Prerequisites: ```sh sudo pacman -S docker docker-compose docker-buildx @@ -112,12 +123,13 @@ sudo systemctl enable --now docker.service ``` -* Build: +- Build: + ```sh docker build -t ipask . ``` -* Run: +- Run: ```sh docker run -d -p 8080:8080 ipask ``` @@ -125,6 +137,7 @@
--- +
@@ -143,12 +156,11 @@ - $HOME/.nginx/key.pem - $HOME/.nginx/cert.pem -* (Option A): Pull the latest container version from hub.docker.com and run it: +- (Option A): Pull the latest container version from hub.docker.com and run it: ```sh docker compose -f docker-compose.yaml up -d ``` - -* (Option B): Build the container from the source and run it: +- (Option B): Build the container from the source and run it: ```sh docker compose up -d ``` @@ -157,6 +169,7 @@
--- +
@@ -164,23 +177,25 @@ -* If running `ipask` as a stand-alone application: +- If running `ipask` as a stand-alone application: + ```sh $ curl :8080 $ wget -qO - :8080 ``` - + Or navigate to `http://:8080` from your browser. -* If runing `ipask` with nginx reverse proxy: +- If runing `ipask` with nginx reverse proxy: + ```sh $ curl -kL $ wget --no-check-certificate -qO - ``` - + Or navigate to `` from your browser. It will automatically redirect to https. - -* Available URL paths: + +- Available URL paths: | Path | Alias | Description | | --- | --- | --- | | `/ip` | | IP address | @@ -188,9 +203,9 @@ | `/xff` | | X-Forwarded-For header | | `/city` | `/ci` | City (if `GEOIP` is enabled) | | `/region` | `/reg` | Region (if `GEOIP` is enabled) | - | `/country` | `/co` | Country (if `GEOIP` is enabled) | + | `/country` | `/co` | Country (if `GEOIP` is enabled) | | `/location` | `/loc` | GPS Coordinates (if `GEOIP` is enabled) | - | `/ua` | | User-Agent request header | + | `/ua` | | User-Agent request header | | `/headers` | `/he` | All headers | | `/version` | `/ver` | Application version (commit hash) |