An on-premise version of the Geocodio API is available for customers with special security or compliance requirements.
The on-premise Geocodio software is available as a Docker image, and can run any host system where Docker is supported. It does not require external internet access, and can as such run in a completely air-gapped environment.
The Geocodio dashboard (including spreadsheet uploads and usage tracking) is not available for on-premise installations. In addition, the Lists API is also unavailable.
For maximum performance, it is recommended to run Geocodio on a separate system that does not share resources with other applications.
Minimum hardware requirements are:
After signing a Geocodio on-premise contract, you will receive a username and passsword which is needed to access the Geocodio software and data files.
These credentials are specific to on-premise and can not be used to access the Geocodio dashboard.
In an internet-connected environment, you need to download the geocodio software as well as a data archive.
The Geocodio docker image is distributed in two versions, the standard version and an unprivileged version where the container runs as a non-root user.
If in doubt, we recommend using the standard version.
# Standard Docker image
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-docker.tar.gz
# Alternative: Unprivileged Docker image
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-docker-unprivileged.tar.gz
# Data archive
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-data.tar.gz
After these have been downloaded, you can transfer them to the host server using your prefered method.
You can also download these files directly from your host server, if it is not in an air-gapped environment.
# Load docker image
docker load < geocodio-docker.tar.gz
# Prepare data directory and move geocodio-data.tar.gz there
mkdir /var/geocodio
mv geocodio-data.tar.gz /var/geocodio
# Load docker image
docker load < geocodio-docker-unprivileged.tar.gz
# Prepare data directory and move geocodio-data.tar.gz there
mkdir /var/geocodio
mv geocodio-data.tar.gz /var/geocodio
# The Geocodio Docker container needs to be able to access /var/geocodio with UID 1001
chown -R 1001:1001 /var/geocodio
The license key is required to run your Geocodio installation. It needs to be placed in the /var/geocodio folder, so it can be read by the software.
echo "<LICENSE KEY CONTENTS>" > /var/geocodio/license.key
Run the docker container by using the docker image that was loaded in the previous step. A volume is necessary to load the data archive.
An environment variable is set to specify the API key that should be used for your Geocodio installation. The API key can be set to any alphanumeric string without spaces.
If openssl is available, you can generate a random API key value like so:
export GEOCODIO_API_KEY=$(openssl rand -base64 32 | tr -d "=+/")
echo $GEOCODIO_API_KEY
export GEOCODIO_API_KEY="YOUR_CHOICE_OF_API_KEY_VALUE"
docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY geocodio:latest
# or if using the unprivileged version:
# docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY geocodio-unprivileged:latest
The first time the container is started, it will take a while before the software is available as the data archive is being extracted and prepared. This process usually takes at least 1 hour. This may be a good time to grab a cup of coffee ☕
You can check the status of this process by tailing its logs:
docker logs -f geocodio
You will now be able to access the API, using the same endpoints as described in the Geocodio Docs.
curl "http://YOUR_SERVER_IP_ADDRESS/v1.7/geocode?q=1109+N+Highland+St%2c+Arlington+VA&api_key=YOUR_CHOICE_OF_API_KEY_VALUE"
Updating Geocodio on-premise requires downloading a new release of the software and data archive. You can follow the same process as with installation.
The Geocodio API is completely stateless and the docker container does not store any permanent information or settings. Because of this, you can replace the docker image and data archive and delete previous data entirely.
Geocodio does not ship with SSL support built-in. We recommend using a reverse proxy for SSL terminaton, such as jwilder/nginx-proxy , optionally paired with jrcs/letsencrypt-nginx-proxy-companion.
It is possible to run Geocodio in "low memory mode" which reduces the memory allocation of the software.
Note: Enabling low memory mode disables support for reverse geocoding. Forward geocoding is not affected.
This mode can be enabled to let Geocodio run on hardware with as little as 2GB available memory.
To enable, set the LOW_MEMORY_MODE environment variable to true, like so:
docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY -e LOW_MEMORY_MODE=true geocodio:latest
Geocodio listens on port 80 per default, it is possible to overwrite the default port using the APP_PORT environment variable.
docker run -d -p 8888:8888 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY -e APP_PORT=8888 geocodio:latest
If a health check is needed for e.g. an upstream loadbalancer, the following URL can be used:
curl -s -o /dev/null -w "%{http_code}" http://YOUR_SERVER_IP_ADDRESS/healthcheck
Monitor the HTTP status code to determine the health status of the service.
| HTTP Status Code | Description |
|---|---|
| 200 OK | Healthcheck is passing |
| 503 Service Unavailable | App is still booting |
| Any other status code | Healthcheck failed |
To decrease startup time for additional instances, it is possible to copy the prepared data directory from an existing Geocodio software instance to a new one.
This can be done as follows:
# Stop currently running Geocodio container to prevent file corruption
docker stop geocodio
# Use your preferred method to copy the data directory
scp -r /var/geocodio some-other-instance-ip-address:/var/geocodio
# Start the Geocodio container again
docker start geocodio