Enable Docker (Optional)

Last Updated: November 2021

If you would like to use Docker to start supporting services such as THREDDS or GeoServer, you'll need to start the Docker service and enable it so that it will start automatically in the future. The following tutorial demonstrates how to enable Docker and install THREDDS and GeoServer using the tethys docker command.

Enable Docker

Enabling Docker to start automatically can be done as follows:

default
sudo systemctl enable --now docker

THREDDS

The recommended pattern for installing THREDDS on the Azure virtual machine is as follows:

Create New Docker Container

  1. Create a new THREDDS Docker container using the tethys docker command:

    default
    tethys docker init -c thredds

  2. Provide appropriate values to the prompts with the following considerations:

    • Use a secure password for the TDM Password field.

    • Specify the hostname of the VM for TDS Host.

    • Do no specify values greater than the amount of memory available to the VM for the Heap Size variables.

  3. Bind the THREDDS data directory to the host when prompted and specify /opt/tethys/data/thredds as the location.

  4. Start the THREDDS server:

    default
    tethys docker start -c thredds

  5. Open the $TETHYS_HOME/config/tethys_nginx.conf and add an entrypoint for the THREDDS server to the server section as follows:

    default
    # tethys_nginx.conf

# the upstream component nginx needs to connect to
upstream channels-backend {
    server 127.0.0.1:8000;
}

# configuration of the server
server {
    # the port your site will be served on
    listen      80;

    ...

    # Thredds Location
    location ~/thredds(.*)$ {
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
        proxy_pass http://127.0.0.1:8383/thredds$1$is_args$args;
    }

    location @proxy_to_app {
        proxy_pass http://channels-backend;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $server_name;
    }
}

  6. Restart the NGINX server:

    default
    sudo systemctl restart nginx

  7. Access the THREDDS server at the following URL: http://<domain_name>/thredds

Create Tethys Service

Now that you have a working THREDDS server, create a Tethys Service for apps to use:

  1. Log in to the Tethys Portal with an admin account.

  2. Select Site Admin from the dropdown menu at the top-right.

  3. Click on the Spatial Dataset Services link under the TETHYS SERVICES section.

  4. Click on the ADD SPATIAL DATASET SERVICE button.

  5. Fill the form out as follows:

    • Name: A descriptive name for the service (e.g.: <domain_name>_thredds)

    • Engine: THREDDS

    • Endpoint: http://<domain_name>/thredds

    • Public Endpoint: http://<domain_name>/thredds

    • Apikey: <leave blank>

    • Username: <leave blank>

    • Password: <leave blank>

  6. Press the SAVE button to save the service.

Add Data

Add datasets to the THREDDS server by adding it to the $TETHYS_HOME/data/thredds directory. Then edit/add catalog configuration files in the same location. Refer to the THREDDS Primer tutorial for an overview of working with THREDDS.

Start/Stop/Restart

Start, stop, and restart the THREDDS container using either the tethys docker commands:

default
tethys docker [start|stop|restart] -c thredds

or the native docker commmands:

default
docker [start|stop|restart] tethys_thredds

GeoServer

The recommended pattern for installing GeoServer on the Azure virtual machine is as follows:

Create New Docker Container

  1. Create a new GeoServer Docker container using the tethys docker command:

    default
    tethys docker init -c geoserver

  2. Provide appropriate values to the prompts with the following considerations:

    • Number of GeoServer Instances: no more than number of processors on VM

    • Number of GeoServer Instances with REST API Enabled: 1 is recommended

    • Specify number of processors and set to number of processors VM has

    • Default timeout value is ok

    • Max memory is for each GeoServer instance (e.g. specifying 500 MB for 2 GeoServer instances would be 1 GB total).

    • Min memory is for each GeoServer instance (e.g. specifying 500 MB for 2 GeoServer instances would be 1 GB total).

  3. Bind the GeoServer data directory to the host when prompted and specify /opt/tethys/data/geoserver as the location.

  4. Start the GeoServer server:

    default
    tethys docker start -c geoserver

  5. Open the $TETHYS_HOME/config/tethys_nginx.conf and add an entrypoint for the GeoServer server to the server section as follows:

    default
    # tethys_nginx.conf

# the upstream component nginx needs to connect to
upstream channels-backend {
    server 127.0.0.1:8000;
}

# configuration of the server
server {
    # the port your site will be served on
    listen      80;

    ...

    # GeoServer Location
    location ~/geoserver(.*)$ {
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
        proxy_pass http://127.0.0.1:8181/geoserver$1$is_args$args;
    }

    location @proxy_to_app {
        proxy_pass http://channels-backend;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $server_name;
    }
}

  6. Restart the NGINX server:

    default
    sudo systemctl restart nginx

  7. Access the GeoServer server at the following URL: http://<domain_name>/geoserver

Open Port 8181

Open port 8181 for the Azure VM as follows:

  1. Navigate to the Overview page for the VM Resource.

  2. Click on Networking in left navigation panel.

  3. Click on the Add inbound port rule button.

  4. Fill out the Add inbound security rule form as follows:

    • Source: Any

    • Source port ranges: *

    • Destination: Any

    • Service: Custom

    • Destination port ranges: 8181

    • Protocol: TCP

    • Action: Allow

    • Priority: <use_default>

    • Name: GeoServer

    • Description: <leave_blank>

  5. Press the Add button.

Create Tethys Service

Now that you have a working GeoServer server, create a Tethys Service for apps to use:

  1. Log in to the Tethys Portal with an admin account.

  2. Select Site Admin from the dropdown menu at the top-right.

  3. Click on the Spatial Dataset Services link under the TETHYS SERVICES section.

  4. Click on the ADD SPATIAL DATASET SERVICE button.

  5. Fill the form out as follows:

    • Name: A descriptive name for the service (e.g.: <domain_name>_geoserver)

    • Engine: GeoServer

    • Endpoint: http://<domain_name>/geoserver

    • Public Endpoint: http://<domain_name>/geoserver

    • Apikey: <leave blank>

    • Username: admin

    • Password: geoserver

  6. Press the SAVE button to save the service.

Start/Stop/Restart

Start, stop, and restart the GeoServer container using either the tethys docker commands:

default
tethys docker [start|stop|restart] -c geoserver

or the native docker commmands:

default
docker [start|stop|restart] tethys_geoserver

What about the PostGIS Docker?

You may be wondering why there aren't instructions for the PostGIS Docker container? The PostGIS docker container is a PostgreSQL server with the PostGIS extension installed. In the Azure Tethys Platform VM image, the system packages of PostgreSQL and the PostGIS extension are both installed. It should not be necessary to use the PostGIS Docker.