With more than half of the American people living along our Nation's coasts, extreme beach and cliff erosion can dramatically alter coastal ecosystems, cause billions of dollars' worth of coastal development, and even threaten human life.
Through projects like the National Assessment of Coastal Change Hazards and regional studies of nearshore processes, the US Geological Survey is uncovering the science behind coastal change hazards and providing data, tools, and scientific knowledge to help coastal planners, resource managers, and emergency operations as they work to reduce risk along our coastlines.
This project has support for running locally via Docker. The first step in getting the projcet to run in docker is to create the SSL certificate keystore and trust store that the project needs.
Setting up the Docker Containers
1). Creating the keystore
In the project
Dockerdirectory run the following command where
<your docker IP>is replaced with the IP address of the docker container that your CCH Portal service will be deployed on.
keytool -genkey -noprompt -keystore key-store.jks -validity 999 -keysize 2048 -alias cch-portal -keyalg RSA -storepass changeit -dname "CN=<your docker IP>, OU=owi, O=owi, L=middleton, S=WI, C=US"
Note that the keystore password
-storepasscan be changed from
changeitto another value of your choice.
2). Modifying configuration
compose.env file located in the project root directory contains example values for all of the necessary configuration variables when running the docker containers. If you launch CCH using
docker-compose then this file will be automatically picked up and applied to the containers.
Several of the configuration values in
compose.env may need to be changed if your docker vm does not have an ip address of
3). Building and running the docker containers
If building from local sources, prior to building the docker containers the CCH Maven project must first be built so that the WAR files are placed into the targe directories. There should be a total of 3 WAR files created, 1 in each of
There are 2 build arguments that can be supplied which will modify the built containers. The first is required when building your images, the second is optional and only needs to be supplied if necessary.
KEYSTORE_PASSWORD- [REQUIRED] This should be the password that you gave the keystore you created previously. This must be supplied even if you used the default keystore password
doi_network- [OPTIONAL] Set this to true if you are having trouble pulling the necessary files for the docker containres during build and you are behind the DOI network. It's possible that the SSL inspection certificate is casuing problems.
When running the
Docker buildcommands these arguments can be passed in as follows:
KEYSTORE_PASSWORD=newpass docker-compose up
Navigate to the coastal hazards project root directory and exectue the following command (note if you are on Windows this must be exectued from the Docker Machine context).
This should being the process of building and then launching all of the docker containers needed for this project. This process will take some time, possibly in upwards of 15 minutes.
Once the portal has finished building and starting it should be accessible from
<your docker IP>:8080/coastal-hazards-portal/
Stopping the docker containers
In order to bring down the running cch stack run the following command:
This will bring down all of the running CCH services defined in the
docker-compose.yml file. Note that running this command will also REMOVE the associated docker containers meaning all data stored in them will be lost.
An alternative method for only brining down select services is to run
docker ps to find the
container ID of the service that you'd like to bring down. Once you've found the
container ID run
docker stop <container ID> to stop that service and then, if you'd like to also remove the container, run
docker rm <container ID>.
Modifying the docker images
When you launch a service using
docker-compose it does NOT always re-build the docker image for the service it is trying to launch. If there is already an existing image for the service you'd like to launch then it will use that rather than building a new one.
In order to build a new docker image for a specific service you can either remove the existing image (which will force
docker-compose to rebuild it), or you can overwrite it with a newer image using
If you remove the existing image note that the entire image building process will need to run again, but if you simply run
docker build and overwrite the existing image Docker will re-use the parts of the existing image that have not been modified.
In order to use
docker build first navigate into the directory containing the
Dockerfile of the service that you would like to rebuild. In this directory open a terminal and run
docker build -t <image name> . where
<image name> matches the name of the image for that service as defined in the
docker-compose.yml file. Build arguments can be passed into the
docker build command in the same manner as the
docker-compose up command (described above). Example:
KEYSTORE_PASSWORD=newpass docker build -t cch-portal .
Any re-built services can then be brought up via the service-specific version of
docker-compose described in point
Additional Important Notes below.
Building from local sources vs building from artifacts
Several of the sub-project docker files support buildling from local sources instead of pulling a specific artifact version from the CIDA Nexus. The sub-projects that support this are
These projects have local-source building enabled by default. In order to switch to building from a pre-built artifact open the
Dockerfile in each project, comment out the
Local Build section, and uncomment the
Artifact Build section. Additionally, check that the desired artifact version is correctly specified in the
ARG at the top of the
Additional Important Notes
It is recommended that you primarily use the docker containers for running the Rserve, PyCSW, and PostgreSQL portions of the application. Due to the large size of most files that are uploaded into the portal it requires a very large Docker VM to store a decent number of items. In order to launch only a subset of the applications services run a command similar to the following (you can find the service names in the
docker-compose.ymlfile in the project root directory).
docker-compose up cch_postgres cch_pycsw cch_rserve
The ports that are described in the
compose.envfor the different services are the ports that they will be exposed on from Docker, not necessarily the ports that the services themselves are running on within the containers. The ports in your
compose.envfile should match up with the ports on the left of side of the
portsargument for that service in the
docker-compose.ymlfile. The ports argument is defined as
<port to be exposed on from the Docker IP>:<port service is running on within the container>. For example, the
cch_n52_wpsservice runs on port
8080in the container, however it is being exposed by docker on port
8082(as shown by
portargument in the
docker-compose.ymlfile) and is thus accessible from
<your docker IP>:8082and not accessible from
<your docker IP>:8080.
<your docker IP>:8080is serving the
cch_portalservice, which is also exposed on port
8080within its container as shown by its