4.2 Docker

This is a short documentation on how to start with Docker and PEcAn. This will not go into much detail about about how to use Docker – for more details, see the main Docker topical page.

  1. Install Docker. Follow the instructions for your operating system at https://www.docker.com/community-edition#/download. Once Docker is installed, make sure it is running. To test that Docker is installed and running, open a terminal and run the following commands:

    docker run hello-world

    If successful, this should return a message starting with "Hello from Docker!". If this doesn’t work, there is something wrong with your configuration. You may need to open the Docker desktop app to complete the installation. Refer to the Docker documentation for debugging.

    NOTE: Depending on how Docker is installed and configured, you may have to run this command as sudo. Try running the command without sudo first. If that fails, but running as sudo succeeds, see these instructions for steps to use Docker as a non-root user.

  2. Install docker compose. If you are running this on a Mac or Windows this might be already installed. On Linux you will need to install this it separately; see https://docs.docker.com/compose/install/.

    To see if docker compose is successfully installed, use the following shell command:

    docker compose version

    This should print the current version of docker-compose. We have tested the instruction below with versions of docker compose 1.22 and above.

  3. Download the PEcAn docker compose file. It is located in the root directory of the PEcAn source code. For reference, here are direct links to the latest stable version and the bleeding edge development version. (To download the files, you should be able to right click the link and select “Save link as”.) Make sure the file is saved as docker-compose.yml in a directory called pecan.

  4. Initialize the PEcAn database and data images. The following docker compose commands are used to download all the data PEcAn needs to start working. For more on how they work, see our Docker topical pages.

    1. Create and start the PEcAn database container (without any data)

      docker compose up -d postgres

      If this is successful, the end of the output should look like the following:

      Creating pecan-postgres-1 ... done

    2. “Initialize” the data for the PEcAn database.

      docker run --rm --network pecan_pecan pecan/db

      This should produce a lot of output describing the database operations happening under the hood. Some of these will look like errors, but this is normal. This command succeeded if the output ends with the following (the syntax for creating a new user for accessing BetyDB):

      docker compose run bety user 'login' 'password' 'full name' 'email' 1 1

    3. Add a user to BetyDB using the example syntax provided as the last line of the output of the previous step:

      # guest user
docker compose run --rm bety user guestuser guestuser "Guest User" guestuser@example.com 4 4

# example user
docker compose run --rm bety user carya illinois "Carya Demo User" carya@example.com 1 1

    4. Download and configure the core PEcAn database files.

      docker run -ti --rm --network pecan_pecan --volume pecan_pecan:/data --env FQDN=docker pecan/data:develop

      This will produce a lot of output describing file operations. This command succeeded if the output ends with the following:

      ######################################################################
Done!
######################################################################

    5. Download the pecan/docker/env.example & save it as .env file. Now, open the .env file & uncomment the following lines:

      COMPOSE_PROJECT_NAME=pecan
PECAN_VERSION=develop

      Setting PECAN_VERSION=develop indicates that you want to run the bleeding-edge develop branch, meaning it may have bugs. To go ahead with the stable version you may set PECAN_VERSION=latest or PECAN_VERSION=<release-number> (For example 1.7.0). You can look at the list of all the releases of PEcAn to see what options are availble.

  5. Start the PEcAn stack. Assuming all of the steps above completed successfully, start the full stack by running the following shell command:

    docker compose up -d

    If all of the containers started successfully, you should be able to access the various components from a browser via the following URLs (if you run these commands on a remote machine replace localhost with the actual hostname).

To shut down the docker images run docker-compose stop. For troubleshooting and advanced configuration, see our Docker topical pages.