Skip to content

Getting Started

ReadyMap is a Django based Python application at it's core, but it depends on numerous services to be up and running and configured to operate.

To make running ReadyMap on your own hardware simpler, we're providing pre-built Docker images that you can run with minimal configuration.

Installing Docker

We recommend installing Docker for your operating system using the official instructions provided here

Installing Docker Compose

docker-compose allows you to define multiple services that work together and bring them up as a system. You can follow instructions to install docker-compose here

Running Docker behind a proxy

If you are in a corporate environment that runs behind a proxy, you may have to configure Docker to use your proxy in order for it to be able to access the Internet. You can follow the instructions here to configure the proxy.

Log into Docker Hub

ReadyMap is commercial software and is only available to authorized users via Docker Hub.

To log into Docker Hub run

sudo docker login

and enter your credentials.

Configure docker-compose.yml

ReadyMap depends on a few services, most notably Redis and PostgreSQL. Each of these services will be ran in their own containers. We can maintain isolation of these services by using docker-compose

Create a directory called "readymap" to store the configuration files

mkdir readymap

Create a file within the readymap directory called docker-compose.yml with the following contents

services:
  # Database
  db:
    image: postgis/postgis:16-3.4-alpine
    privileged: true
    environment:
      POSTGRES_DB: readymap
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: readymap
    volumes:
      - readymap_db:/var/lib/postgresql/data
    restart: always

  # Redis
  redis:
    image: redis:5.0-alpine
    restart: always

  # ReadyMap
  readymap:
    image: pelicanmapping/readymap:4.6.0
    privileged: true
    restart: always
    volumes:
      - /data:/data
      - /tiles:/tiles
    ports:
      - "80:80"
    environment:
      - LICENSE_TEXT=XXX
    depends_on:
      - db
      - redis

volumes:
  # Database storage volume
  readymap_db:

This docker-compose.yml file references readymap:4.6.0, which is the latest version of ReadyMap.

Make sure to update your LICENSE_TEXT environment variable in the ReadyMap container with your license string.

You'll notice that there are a few volumes settings in this file. These map your local directories to directories that will be bind mounted within the Docker containers. These are called bind mounts and essentially mount the local directory into the container. The volume definitions are local_path:container_path. You'll also notice there is a readymap_db volume at the end of the docker-compose.yml file, this is a Docker volume and is managed completely by Docker. Docker volumes can be useful especially for PostgreSQL as it is very particular about directory permissions for it's data and using a Docker volume will work on both Windows and Linux deployments.

If you want to use different locations for the bind mounts, just change the volume definitions.

readymap_db will store all of your PostgreSQL data. This will persist even if you accidentally delete the container. /data is where you'll place all of the geospatial data you want to load into ReadyMap. /tiles is where your tiles will be stored. We recommend this directory be part of an XFS file system or another similiar file system that can handle massive numbers of inodes.

Your /data and /tiles directories should have open permissions on them so any user can read and write to them

sudo chmod a=rwx /data
sudo chmod a=rwx /tiles

Running ReadyMap

Now that you've configured your directories, you're ready to run ReadyMap!

cd readymap
sudo docker compose up -d

This will launch containers for PostgreSQL, Redis and ReadyMap.

If all goes well, you should be able to go to http://localhost/readymap and login with the credentials readymap / readymap

You can see what is going on in each container using

# All containers
sudo docker compose logs

# Specific container
sudo docker compose logs readymap

Upgrading ReadyMap

When running in production you should be using versioned container tags and not the pelicanmapping/readymap:latest tag. This is important so you can know exactly what version you are running.

To get a new version of ReadyMap you can update your docker-compose.yml file to point to the new version, pull it and restart the container with the new version.

cd readymap
sudo docker compose pull
sudo docker compose up -d

This will pull the specified ReadyMap and restart the container with the new version.

Changing your password

If you ever forget your password you can change it using the command line by running this command

docker compose exec readymap ./manage.py changepassword USERNAME

Saving and restoring the ReadyMap database

To backup your ReadyMap database you can run the command

docker compose exec readymap readymap_backup /data/backup.db

Notice that the backup command is running inside the container, so the export path you provide needs to be in a volume that is mounted in the container.

To restore a backup you can run the command

docker compose exec readymap readymap_restore /data/backup.db

Getting Docker Images without an Internet Connection

If you want to run ReadyMap on a machine with no Internet connection, you'll need to save the Docker images from another machine and load them onto your disconnected machine.

  1. Install ReadyMap via Docker using docker compose like normal.
  2. Save each of the images images in use the docker-compose.yml file to an archive.
docker save pelicanmapping/readymap:4.6.0 | gzip > readymap_4.6.0.tar.gz
docker save mdillon/postgis:16-3.4-alpine | gzip > postgis_16-3.4-alpine
docker save redis:5.0-alpine | gzip > redis_5.0-alpine.tar.gz
  1. Copy the tar.gz files to your disconnected machine using a thumb drive or some other means.
  2. Load the images into Docker locally
docker load < readymap_4.6.0.tar.gz
docker load < postgis_16-3.4-alpine
docker load < redis_5.0-alpine.tar.gz
  1. You should now be able to create the docker-compose.yml file on your disconnected machine and run docker compose up -d to start ReadyMap.

Running ReadyMap with Podman

RedHat Linux advices users to use podman to run containers instead of Docker. podman can use the same docker-compose.yml file as docker-compose using podman-compose. To install podmand and podman-compose on RedHat you can run the following commands 

sudo yum -y install podman
sudo yum –y install python3-pip
sudo pip3 install podman-compose

To get the docker images you can replace the docker login command with podmand login like this: 

podman login docker.io -u user -p pass

In the directory with your docker-compose.yml file you can run this command to launch your containers: 

podman-compose up

Note

It is very important to have the privileged: true section in your docker-compose.yml for podman**

PostgreSQL

ReadyMap needs a PostgreSQL/PostGIS database to store it's configuration. The docker-compose.yml file shows how to run PostgreSQL locally with a container. If you want to run your own database or use a managed offering like AWS RDS you can delete the database section from your docker-compose.yml and configuring the ReadyMap container with the following environment variables:

  • DATABASE_HOST - The database host. Default is "db".
  • DATABASE_USER - The database user. Default is "postgres"
  • DATABASE_PASSWORD - The database password. Default is "readymap"
  • DATABASE_NAME - The database name. Default is "readymap"
  • DATABASE_PORT - The database port. Default is 5432.

Redis

ReadyMap uses Redis as a job orchestrator and an in memory cache. The docker-compose.yml file shows you how you can run Redis locally, but you can use an external Redis like AWS ElastiCache by removing the redis section from your docker-compose.yml and configuring the ReadyMap container with the following environment variables:

  • REDIS_HOST - The redis host. Default is "redis".

Sentry

ReadyMap has support for monitoring errors using Sentry. You can sign up for a Sentry account and create a new project. From your project you can go to Settings | SDK Setup | Client Keys (DSN) and copy your DSN.

Once you have your DSN, you can configure ReadyMap to send any errors to Sentry using the SENTRY_DSN environment variable. 

readymap:
    image: pelicanmapping/readymap:4.6.0
    privileged: true
    restart: always
    volumes:
      - /data:/data
      - /tiles:/tiles
    ports:
      - "80:80"
    environment:
      - LICENSE_TEXT=XXX
      - SENTRY_DSN=YOUR_SENTRY_DSN

SSL

If you are running ReadyMap on the public Internet, it is recommended to run ReadyMap with SSL support to encrypt your traffic. How you create your SSL certificates is up to you, it is recommended to consult the best practices of your organization.

Once you have your SSL certificate, you need to edit your docker-compose.yml file to enable SSL. Here is an example.

  readymap:
    image: pelicanmapping/readymap:4.6.0
    privileged: true
    restart: always
    volumes:
      - /data:/data
      - /tiles:/tiles
      # Bind mount a directory with your ssl certificates to the
      # /ssl directory inside of your container
      - /path/to/ssl:/ssl
    ports:
      # Open port 443 for HTTPS
      - "443:443"
      # Optionally open port 80 so that HTTP requests will work, redirecting to HTTPS
      - "80:80"
    environment:
      - LICENSE_TEXT=XXX
      # Enable SSL
      - USE_SSL=YES
      # Configure your SSL certificate, chain and key files.
      - SSL_CERTIFICATE_FILE=/ssl/ssl_certifate.pem
      - SSL_CERTIFICATE_CHAIN_FILE=/ssl/ssl_certifate_chain.pem
      - SSL_CERTIFICATE_KEY_FILE=/ssl/ssl_key.pem
    depends_on:
      - db
      - redis

The following environment variables are required to enable SSL support in ReadyMap

  • USE_SSL - Run ReadyMap with SSL support.
  • SSL_CERTIFICATE_KEY_FILE - Absolute path to your SSL key file.
  • SSL_CERTIFICATE_FILE - Absolute path to your SSL certificate file.
  • SSL_CERTIFICATE_CHAIN_FILE - Absolute path to your SSL certificate chain file. If you do not have a separate chain file set this to your SSL_CERTIFICATE_FILE.

Log Management

ReadyMap sends all of it's logs to stdout and stderr and tries to do as much structured logging as possible. There are many options for viewing container logs.

The simplest method of viewing the logs is just to run this command: 

docker compose logs --follow readymap
This will attach to the readymap container and display it's logs on the console.

Dozzle is a nice web based tool for displaying container logs. You can add this snippit to your services section in your docker-compose.yml file for a simple Dozzle deployment. 

dozzle:
    container_name: dozzle
    image: amir20/dozzle:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 8080:8080
You can then navigation to http://YOUR_SERVER_ADDRESS:8080 and see your container logs.

Follow the Dozzle documentation for more advanced usage and configuration.

Notifications

ReadyMap uses Apprise to provide notifications when key events happen like when a layer is created or deleted or when a tiling job starts or finishes. Apprise allows you to send notifications to a large collection of services such as Slack, email or SMS just by editing a single config file. To enable Apprise support in your ReadyMap installation you need to create an apprise.yml file that configures your notifications and then mount it into your ReadyMap container at /etc/apprise.yml. For example, you can create an apprise.yml file in the same directory as your docker-compose.yml file and modify your ReadyMap service to mount it.

  readymap:
    image: pelicanmapping/readymap:4.6.0
    volumes:
      - /data:/data
      - /tiles:/tiles
      # Mount the apprise.yml configuration file into the ReadyMap container.
      - ./apprise.yml:/etc/apprise.yml

Configuring Apprise is outside of the scope of the this document, but a sample apprise.yml to send notifications to Slack might look like this:

asset:
  app_id: ReadyMap
  app_desc: ReadyMap Notifications
  app_url: https://myreadymapserver.com/readymap
urls:
  - slack://TokenA/TokenB/TokenC/