GeoDB Cities API

Setup

1. Email geodb-support@wirefreethought.com with the egress IPs of your instance(s). We will need to whitelist them before your instance(s) can properly start.
2. Make sure the following hosts/ports are externally accessible from your instance(s):
   • wft-geo-data-shard-00-00-t70if.mongodb.net:27017
   • wft-geo-data-shard-00-01-t70if.mongodb.net:27017
   • wft-geo-data-shard-00-02-t70if.mongodb.net:27017
   • wft-license-service.dyndns.ws:80
3. Wait for our reply that your egress IPs have been whitelisted.
4. Define a MANAGEMENT_PORT environment variable as the GeoDB management port to use (for health-check endpoints).
5. Define a PORT environment variable as the GeoDB port to use.
6. Define a JAVA_OPTS environment variable with the following recommended settings (a single line with a space separating each setting, as in JAVA_OPTS="setting1 setting2 ..."):
   • -XX:MaxRAMPercentage=80
   • -XX:MaxMetaspaceSize=256M
   • -Xss256k
   • -XX:ActiveProcessorCount=NUM_CORES_TO_USE
   • -XX:+UseG1GC
   • -XX:+UseStringDeduplication
7. Start the Docker container:

   docker run \
       -d -m 9g \
       -p $PORT:$PORT \
       -p $MANAGEMENT_PORT:$MANAGEMENT_PORT \
       -e SPRING_PROFILES_ACTIVE=selfHosted,prod \
       -e LICENSE_ACTIVATION_CODE=Your-License-Activation-Code \
       -e LICENSE_EMAIL=Your-Subscriber-Email \
       -e PORT=$PORT \
       -e MANAGEMENT_PORT=$MANAGEMENT_PORT \
       -e JAVA_OPTS="$JAVA_OPTS" \
       wirefreethought/geo-data-api_self-hosted
   

8. Find out the id of the running container:

   docker ps
   

9. Follow the container log:

   docker logs GeoDB-Container-Id --follow
   

10. Wait for the log message indicating successful license checkout:

    License checked out. Expires at MM-dd-yy hh:mm:ss a
    

You should now be able to access the instance(s) at http://your-host:your-port/v1/some-geodb-endpoint (e.g, http://localhost:10000/v1/geo/cities).

Important Notes

• About 10 seconds after startup, GeoDB will attempt to validate your license with our cloud-based licensing service. Afterwards, it will periodically renew the license checkout with that service. Although GeoDB will start and stay running, you will only be able to access its endpoints while the license checkout is valid.
• Because the license service has no way of reliably tying your specific instance(s) to an existing license checkout, every startup of your instance(s) will result in a new checkout. Since you are limited to a maximum of 5 checkouts at a time and a checkout lease is good for one day, this has implications for how often you can restart your instance(s) within a given 24-hour period. Specifically, if you restart your instance(s) 5 times in a single day, the license checkout will be refused on the sixth restart. In this case, you will have to wait for the license service to trim the orphaned checkouts before your instance(s) will successfully activate.
• Health check endpoints are available on the management port you defined. Specifically:
  • http://your-host:your-management-port/actuator/health/readiness
  • http://your-host:your-management-port/actuator/health/liveness​
• Both ports can be any values so long as they are distinct from each other and don't conflict with an existing process on your network