GeoDB Cities API

Self-Hosting | Setup


  1. Email 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):
  3. Wait for our reply that your egress IPs have been whitelisted.
  4. Define a PORT environment variable as the GeoDB port to use.
  5. Start the Docker container:
    docker run \
        -d -m 8g \
        -p $PORT:$PORT \
        -e SPRING_PROFILES_ACTIVE=selfHosted,prod \
        -e LICENSE_ACTIVATION_CODE=Your-License-Activation-Code \
        -e LICENSE_EMAIL=Your-Subscriber-Email \
        -e PORT=$PORT \
  6. Find out the id of the running container:
    docker ps
  7. Follow the container log:
    docker logs GeoDB-Container-Id --follow
  8. 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-host-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.
  • The PORT environment variable can be any value you like that doesn't conflict with an existing process on your network.
  • Although it's possible to run with as little as 4 GB memory, we recommend 8 GB (-m 8g) to prevent JVM garbage-collection thrashing and give GeoDB plenty of room to breathe. This becomes especially important under load.