Introduction

The reasoning behind this implementation is very simple: it's a single Docker container running an instance of ERDDAP. So, the main requirement for it to run is Docker. The user must have either sudo privileges or be in the docker user group to be able to use Docker, see the documentation for more details. In addition to Docker, Python scripts (located in the utils/ directory) are used to generate the configuration files required for ERDDAP.

The original Docker image is available here. It is based on ERDDAP v2.22.

Installation

The first step to reproducing the implementation is cloning the repository. Since ERDDAP will be writing into this directory, it is important to clone it in a location with sufficient space, e.g. the /data/ partition.

# Go to the appropriate directory
$ cd /data

# Clone the repository and enter it
$ git clone https://github.com/bio-oracle/bio-oracle-erddap && cd bio-oracle-erddap

After that, check if the Docker container builds correctly. Make sure your user either has sudo privileges or is in the docker user group. You can check this with:

$ groups

If you see sudo and docker in the output, you are all good. Otherwise, you'll have to add your user to these groups. A user with admin privileges must run these two commands:

# Add to sudoers
$ sudo usermod -aG sudo <USERNAME>

# Add to docker
$ sudo usermod -aG docker <USERNAME>

Before running the container, read the comments inside the setup_template.xml and make the requested changes. Then rename the file:

$ mv setup_template.xml setup.xml

setup.xml is the file with all of the settings which specify how your ERDDAP behaves.

Deploying the Docker container

Once the user is in the sudo and docker groups, to start the container simply run:

$ docker compose up -d

Make sure that you are in this repository's root directory when you run this. This command uses Docker compose to start the Docker container, and it depends on the docker-compose.yml file at the root of the repository. The -d flag means "detached", that is, to run the container in the background.

You can also start a screen and run the docker compose up command from there. In this case, you can omit the -d option, so you can see status messages within the screen.

If you're running this for the first time, you'll see Docker downloading the image and then compiling it. Once the command completes, the output should show something like this:

[+] Running 1/1
 ⠿ Container bio-oracle-erddap  Started              0.8s

That means that the container started correctly. You should be able to navigate to http://erddap.bio-oracle.org:8080/erddap/index.html on your browser and see the ERDDAP server online. To see a list of the containers, run:

$ docker ps -a
CONTAINER ID   IMAGE                                    COMMAND                  CREATED      STATUS         PORTS                    NAMES
9d6ae063c8fa   axiom/docker-erddap:2.22-jdk17-openjdk   "/entrypoint.sh cata…"   6 days ago   Up 4 minutes   0.0.0.0:8080->8080/tcp   bio-oracle-erddap

To stop the container, run:

$ docker compose stop
[+] Running 1/1
 ⠿ Container bio-oracle-erddap  Stopped              0.4s

Configuration files

The main configuration file in the application is the compose file, docker-compose.yml. Please have a look at the compose file specification for details. Here's what it may look like:

version: '2'
services:
  erddap:
    container_name: "bio-oracle-erddap"
    image: axiom/docker-erddap:2.22-jdk17-openjdk
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      ERDDAP_MIN_MEMORY: 1G
      ERDDAP_MAX_MEMORY: 2G
    volumes:
      - "${PWD}/erddap/conf/config.sh:/usr/local/tomcat/bin/config.sh"
      - "${PWD}/erddap/conf/robots.txt:/usr/local/tomcat/webapps/ROOT/robots.txt"
      - "${PWD}/erddap/content:/usr/local/tomcat/content/erddap"
      - "${PWD}/erddap/data:/erddapData"
      - "/data/layers:/datasets"
      - "/tmp/:/usr/local/tomcat/temp/"

While it's quite self-explanatory, it's helpful for us to go through the different keys:

• version: deprecated, don't have to worry about this one.
• services: service names that we are deploying. Values will be service definitions, that is, the configuration that is applied to each container started at that service. We have a single service, erddap.
• container_name: string that specifies the container name.
• restart: string that defines the policy applied on container termination.
• ports: mapping of ports from the local machine to the container.
• environment: environment variables in the container. Here we have ERDDAP_MIN_MEMORY and ERDDAP_MAX_MEMORY which define the amount of RAM used by ERDDAP. Good values are 1G for min and the value of the RAM in the machine minus 2 for max (e.g. if the machine has 16GB RAM, set this to 14G).
• volumes: mapping of directories from the local machine to the container. This is probably the most important key in this file, as ERDDAP and the utilities scripts won't work properly if this is not set correctly. The first two files, config.sh and robots.txt, are respectively a file with environment variables for ERDDAP (make sure to populate this) and a file with parameters to avoid web crawlers (see here for more information). The erddap/content and erddap/data directories are directories that ERDDAP will write a bunch of information into, such as logs and other additional files. /data/layers maps to the /datasets directory within the container, where the datasets will be stored. **Make sure that /data/layers is the path on the server (not on the container, which must always be /datasets).

Continue on to to Managing Datasets to learn how to message the ERDDAP datasets in the implementation.