High performance JSON IP and GeoIP REST API (IP Geolocation)
Log | Files | Refs | README | LICENSE

commit 48839041c89db8a368f40600356eed4945074388
parent d2958bf340b7731af90ddfaaca5eaa882cfb1251
Author: Frederic Cambus <>
Date:   Thu, 29 Nov 2018 10:48:13 +0100

Update README to sync with the new reality

Diffstat: | 108+++++++++----------------------------------------------------------------------
1 file changed, 12 insertions(+), 96 deletions(-)

diff --git a/ b/ @@ -16,41 +16,19 @@ ## Description -Telize is a REST API built on Nginx and Lua allowing to get a visitor IP +Telize is a REST API built in C with Kore allowing to get a visitor IP address and to query location information from any IP address. It outputs JSON-encoded IP geolocation data, and supports both JSON and JSONP. -Geolocation operations are performed using Nginx GeoIP2 module which caches -the database in RAM. Therefore, Telize has very minimal overhead and should +Geolocation operations are performed using libmaxminddb which caches the +database in RAM. Therefore, Telize has very minimal overhead and should be blazing fast. ## Requirements -### Nginx modules +### Dependencies -Telize requires Nginx 1.7.4+ compiled with the following modules: - -- Real IP module (Optional HTTP module: --with-http_realip_module) -- Lua module 0.9.17+ (Third party module: [ngx_http_lua_module][1]) -- GeoIP2 module (Third party module: [ngx_http_geoip2_module][2]) - -For optimal performance, please make sure the HttpLuaModule is built -against LuaJIT: - - ldd $(which nginx) | grep lua - -### Lua modules - -Telize requires the following Lua module: - -- Lua CJSON - -Installing via LuaRocks: - - luarocks install lua-cjson - -Alternatively, this module can be installed directly via the operating -system's package manager. +Telize requires [Kore][1] 3.2.0+ and [libmaxminddb][2]. ### GeoIP2 databases @@ -64,55 +42,9 @@ Telize requires the free [GeoLite2 databases][3] from MaxMind. tar xfz GeoLite2-ASN.tar.gz mv */*mmdb . -## Installation - -Copy both `country-code3.conf` and `timezone-offset.conf` in the Nginx -configuration files directory. - -Edit `nginx.conf` to include those configuration files and to add directives -specifying the path to the GeoIP2 database files, within the http block. - - http { - ... - - include /etc/nginx/country-code3.conf; - include /etc/nginx/timezone-offset.conf; +## Building - geoip2 /var/db/GeoIP/GeoLite2-City.mmdb { - $geoip2_continent_code continent code; - $geoip2_country country names en; - $geoip2_country_code country iso_code; - $geoip2_region subdivisions 0 names en; - $geoip2_region_code subdivisions 0 iso_code; - $geoip2_city city names en; - $geoip2_postal_code postal code; - $geoip2_latitude location latitude; - $geoip2_longitude location longitude; - $geoip2_timezone location time_zone; - } - - geoip2 /var/db/GeoIP/GeoLite2-ASN.mmdb { - $geoip2_asn autonomous_system_number; - $geoip2_organization autonomous_system_organization; - } - } - -Then deploy the API configuration file `telize.conf` to the appropriate -location on your system, and reload Nginx configuration. If Telize is -deployed behind a load balancer, read the next section. - -Depending on existing configuration, default values of `map_hash_max_size` -and `map_hash_bucket_size` variables might be too low and Nginx will refuse -to start. - -If this happens, please add the following directives in the `http` block: - - map_hash_max_size 8192; - map_hash_bucket_size 64; - -On busy instances, the maximum number of open files limit must be increased -using the `worker_rlimit_nofile` directive in order to avoid running out of -available file descriptors. +## Configuration ## Access and Error logs @@ -122,29 +54,13 @@ configured manually. If your Telize instance produces lots of logs, this might be of interest: [Log rotation directly within Nginx configuration file][4]. -## Telize and Load Balancers - -When using Telize behind a load balancer, uncomment the following directives -in the server block and set the load balancer IP range accordingly: - - # set_real_ip_from; # Put your load balancer IP range here - # real_ip_header X-Forwarded-For; - -In the `/location` endpoint, replace this directive: - - proxy_set_header X-Real-IP $ip; - -By the following directive: - - proxy_set_header X-Forwarded-For $ip; +## Telize and proxies ## CORS Support (Cross-origin resource sharing) -Telize has CORS enabled by default since version 1.02. The following variables -define CORS behavior, within the `telize.conf` configuration file. +Telize has CORS enabled by default with the following policy: - set $cors "true"; - set $cors_origin "*"; + Access-Control-Allow-Origin: * ## Usage @@ -193,7 +109,7 @@ Latest tarball release: GitHub: -[1]: -[2]: +[1]: +[2]: [3]: [4]: