diff --git a/README.md b/README.md
index b8fe29a..bb5ed20 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
# IP Ask
-Another ifconfig-like web application. This one is written in Python with Flask framework.
+`whatsmyip` type of web application written in Python with Flask framework
-ipask.me
+[ipask.me](https://ipask.me)
---
@@ -11,9 +11,9 @@ Another ifconfig-like web application. This one is written in Python with Flask
-* Install Python:
+* Install Git and Python:
```
- pacman -S python
+ sudo pacman -S git python
```
* Clone the git repository:
@@ -35,6 +35,8 @@ Another ifconfig-like web application. This one is written in Python with Flask
* (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:
@@ -45,19 +47,7 @@ Another ifconfig-like web application. This one is written in Python with Flask
```
curl -L git.io/GeoLite2-City.mmdb -o resources/GeoLite2-City.mmdb
```
- The GeoIP feature is toggled with the `GEOIP` environment variable.
-
-* (Optional) Generate the test key and certificate utilized by the nginx reverse proxy.
-
- You only need this if you utilize `docker-compose.yaml` and run IP Ask behind nginx.
- Review the environment variables inside `resources/generate_cert.sh` and set them accordingly like so:
- ```sh
- CN=yourdomain.com ./resources/generate_cert.sh
- ```
- Or you could use your own key and certificate. `docker-compose.yaml` expects to find them here:
- - $HOME/.nginx/key.pem
- - $HOME/.nginx/cert.pem
---
@@ -68,47 +58,42 @@ Another ifconfig-like web application. This one is written in Python with Flask
+* Environment variables:
+ | Environment variable | Default value |
+ | --- | --- |
+ | GEOIP | `false` |
+ | REVERSE_DNS_LOOKUP | `false` |
+
+* Run using `run.py`:
-* Run using `run.sh`:
```sh
- ./run.sh
+ python run.py
```
- Environment variables:
- | ENV var | Default value |
- | :----: | :----: |
- | GUNICORN_SERVER | ipask |
- | [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 |
- | GEOIP | false |
- | REVERSE_DNS_LOOKUP | false |
Example:
```sh
- REVERSE_DNS_LOOKUP=true GUNICORN_WORKERS=4 GUNICORN_THREADS=2 ./run.sh
+ REVERSE_DNS_LOOKUP=true python run.py
```
-
-* Run using `run.py`:
-
- This will run it without the Python WSGI HTTP Server - [gunicorn](https://gunicorn.org):
+
+* Run using `run.sh` (recommended):
+
+ This will run the application with the Python WSGI HTTP Server - [gunicorn](https://gunicorn.org):
+
```sh
- python run.py
+ ./run.sh
```
-
-* Test:
+ Gunicorn-specific environment variables:
+ | Environment variable | Default value |
+ | --- | --- |
+ | GUNICORN_SERVER | `ipask` |
+ | [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:
```sh
- $ curl :8080[/ip|/host|/xff|/ua|/headers|/city|/country]
- $ wget -qO - :8080[/ip|/host|/xff|/ua|/headers|/city|/country]
+ REVERSE_DNS_LOOKUP=true GUNICORN_WORKERS=3 ./run.sh
```
- Or navigate to `http://:8080` from your browser.
-
----
-## Prerequisites for running in a container
- ```sh
- sudo pacman -S docker docker-compose docker-buildx
- sudo usermod -aG docker $USER
- sudo systemctl enable -now docker.service
- ```
---
@@ -119,6 +104,14 @@ Another ifconfig-like web application. This one is written in Python with Flask
+* Prerequisites:
+
+ ```sh
+ sudo pacman -S docker docker-compose docker-buildx
+ sudo usermod -aG docker $USER
+ sudo systemctl enable --now docker.service
+ ```
+
* Build:
```sh
docker build -t ipask .
@@ -129,12 +122,6 @@ Another ifconfig-like web application. This one is written in Python with Flask
docker run -d -p 8080:8080 ipask
```
-* Test:
- ```sh
- curl :8080[/ip|/host|/xff|/ua|/headers|/city|/country]
- wget -qO - :8080[/ip|/host|/xff|/ua|/headers|/city|/country]
- ```
- Or navigate to `http://:8080` from your browser.
---
@@ -144,26 +131,67 @@ Another ifconfig-like web application. This one is written in Python with Flask
## Run with Docker Compose behind nginx reverse proxy
+
+* Generate a self-signed test key-pair utilized by the nginx reverse proxy.
+
+ Review the environment variables inside `resources/generate_cert.sh` and set them accordingly.
+ For example:
+ ```sh
+ CN=yourdomain.com ./resources/generate_cert.sh
+ ```
+ Or you could use your own key and certificate. `docker-compose.yaml` expects to find them here:
+ - $HOME/.nginx/key.pem
+ - $HOME/.nginx/cert.pem
-* Run:
+* (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:
+ ```sh
+ docker compose up -d
+ ```
+ Use the `--build` option in order to force the build process in case you already have the `ipask` container and want a new one.
+
+
- Two options: Build the container or pull the latest published container version from hub.docker.com
+---
+
+
- * Build and run:
- ```sh
- docker compose up -d
- ```
- Use the `--build` option in order to force the build process in case you already have the `ipask` container and want a new one.
-
- * Pull and run:
- ```sh
- docker compose -f docker-compose.yaml up -d
- ```
-
-* Test:
+## Usage
+
+
+
+* If running `ipask` as a stand-alone application:
```sh
- curl -kL [/ip|/host|/xff|/ua|/headers|/city|/country]
- wget --no-check-certificate -qO - [/ip|/host|/xff|/ua|/headers|/city|/country]
+ $ curl :8080
+ $ wget -qO - :8080
```
- Or navigate to `` from your browser. It will automatically redirect to https and you have to accept the self-signed certificate.
+
+ Or navigate to `http://:8080` from your browser.
+
+* 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:
+ | Path | Alias | Description |
+ | --- | --- | --- |
+ | `/ip` | | IP address |
+ | `/host` | `/h` | Hostname or FQDN (if `REVERSE_DNS_LOOKUP` is enabled) |
+ | `/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) |
+ | `/location` | `/loc` | GPS Coordinates (if `GEOIP` is enabled) |
+ | `/ua` | | User-Agent request header |
+ | `/headers` | `/he` | All headers |
+ | `/version` | `/ver` | Application version (commit hash) |
+