diff --git a/README.md b/README.md index 9db2369..af3984b 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,84 @@ --- +
+ + +## TL;DR + + + +- Run as a stand-alone container + + ```sh + docker run -d -p 8080:8080 prestigen/ipask + ``` + +- Run with nginx reverse proxy + + ```sh + git clone https://github.com/pnedkov/ipask.git + cd ipask/ + CN=yordomain.com ./resources/generate_cert.sh + docker compose -f docker-compose.yaml up -d + ``` + +
+ +--- +
-## Getting started +## Usage + + + +- If `ipask` is running as a stand-alone application on the default port `8080`: + + ```sh + $ curl :8080 + $ wget -qO - :8080 + ``` + + Or navigate to `http://:8080` from your browser. + +- If `ipask` is running 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) | + +
+ +--- + +
+ + +## Run from the source code +### Prerequisites + - Install Git and Python: ``` @@ -54,23 +125,14 @@ curl -L git.io/GeoLite2-City.mmdb -o resources/GeoLite2-City.mmdb ``` -
- ---- - -
- - -## Run from the source code - - - - Environment variables: | Environment variable | Default value | | --- | --- | | GEOIP | `false` | | REVERSE_DNS_LOOKUP | `false` | +### Run + - Run using `run.py`: ```sh @@ -111,17 +173,21 @@
-## Run in a stand-alone container +## Build and run in a container -- Prerequisites: +### Prerequisites: - ```sh - sudo pacman -S docker docker-compose docker-buildx - sudo usermod -aG docker $USER - sudo systemctl enable --now docker.service - ``` +```sh +sudo pacman -S git docker docker-compose docker-buildx +sudo usermod -aG docker $USER +sudo systemctl enable --now docker.service +git clone https://github.com/pnedkov/ipask.git +cd ipask/ +``` + +### Build and run as a stand-alone container - Build: @@ -134,79 +200,18 @@ docker run -d -p 8080:8080 ipask ``` -
+### Build and run with Docker Compose behind nginx reverse proxy ---- +- Generate a self-signed test key-pair utilized by nginx -
- - -## 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 - -- (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. - -
- ---- - -
- - -## Usage - - - -- 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: +- Build and run ```sh - $ curl -kL - $ wget --no-check-certificate -qO - + docker compose up -d ``` - 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) | -