From 742e72d48b9defb08ea4465862d706b7eaf38190 Mon Sep 17 00:00:00 2001 From: Gaurav Chaudhary Date: Fri, 24 Jul 2026 20:21:34 +0530 Subject: [PATCH] Complete Docker docs consolidation under Developer Guide (#3743) Fix broken cross-references after the move from 94_docker using anchor-based same-book links, add Docker to the Developer Guide index, and repair malformed links and missing anchor targets. Signed-off-by: Gaurav Chaudhary --- .../02_demos_tutorials_workflows/01_install_pecan.Rmd | 4 ++-- .../05_developer_workflows/00_developer_guide.Rmd | 3 ++- .../05_developer_workflows/04_docker/00_docker_index.Rmd | 6 ++++-- .../05_developer_workflows/04_docker/01_introduction.Rmd | 4 ++-- .../05_developer_workflows/04_docker/03_architecture.Rmd | 4 ++-- .../05_developer_workflows/04_docker/05_building_images.Rmd | 2 +- .../05_developer_workflows/04_docker/07_migrate.Rmd | 2 +- .../05_developer_workflows/04_docker/08_pecan_api.Rmd | 2 +- book_source/03_topical_pages/12_troubleshooting-pecan.Rmd | 2 +- .../93_installation/00_installation_index.Rmd | 2 +- 10 files changed, 17 insertions(+), 14 deletions(-) diff --git a/book_source/02_demos_tutorials_workflows/01_install_pecan.Rmd b/book_source/02_demos_tutorials_workflows/01_install_pecan.Rmd index 4c21c9e262f..9939aebccef 100644 --- a/book_source/02_demos_tutorials_workflows/01_install_pecan.Rmd +++ b/book_source/02_demos_tutorials_workflows/01_install_pecan.Rmd @@ -12,7 +12,7 @@ This set of instructions will help facilitate your path and the steps necessary ## Docker {#install-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](docker-intro.html). +This will not go into much detail about about how to use Docker -- for more details, see the main [Docker documentation](#docker-intro). 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. @@ -119,7 +119,7 @@ This will not go into much detail about about how to use Docker -- for more deta - Monitor, service that monitors models and shows all models that are online as well as how many instances are online and the number of jobs waiting. The output is in JSON -- http://pecan.localhost/monitor/ To shut down the docker images run `docker-compose stop`. -For troubleshooting and advanced configuration, see our [Docker topical pages](developer-workflows/docker-index.html). +For troubleshooting and advanced configuration, see our [Docker documentation](#docker-index). ## Installation From r-universe {#r-universe} diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/00_developer_guide.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/00_developer_guide.Rmd index fda065a9695..efc704a871d 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/00_developer_guide.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/00_developer_guide.Rmd @@ -1,8 +1,9 @@ # Developer guide {#developer-guide} -Get started with PEcAn development with this guide. You'll learn how to use Git for collaboration, follow PEcAn's coding standards, and update code and databases. Whether you're fixing a bug or adding a new feature, start here. +Get started with PEcAn development with this guide. You'll learn how to use Git for collaboration, follow PEcAn's coding standards, update code and databases, and work with Docker. Whether you're fixing a bug or adding a new feature, start here. * [Update BETY](#updatebety) * [Update PEcAn Code](#pecan-make) * [PEcAn and Git](#pecan-git) * [Coding Practices](#coding-practices) +* [Docker](#docker-index) diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/00_docker_index.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/00_docker_index.Rmd index 862927cdcb2..337f77e3ec8 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/00_docker_index.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/00_docker_index.Rmd @@ -3,10 +3,12 @@ This chapter describes the PEcAn Docker container infrastructure. It contains the following sections: -- [Introduction to Docker](01_introduction.html) -- Brief introduction to Docker and `docker-compose` +- [Introduction to Docker](#docker-intro) -- Brief introduction to Docker and `docker-compose` - [Docker quickstart](#docker-quickstart) -- Brief tutorial for setting up a Docker-based PEcAn instance - [PEcAn Docker Architecture](#pecan-docker) -- Detailed description of the containers comprising the PEcAn Docker-based infrastructure - [Dockerfiles for models](#model-docker) -- General guide for writing Dockerfiles for new models - [Building and modifying images](#docker-build-images) -- [Troubleshooting Docker]{#docker-troubleshooting} +- [Troubleshooting Docker](#docker-troubleshooting) - [Migrating from VM to Docker](#docker-migrate) -- Steps to migrate from running PEcAn on a VM to a docker. +- [The PEcAn Docker API](#pecan-api) +- [RabbitMQ](#rabbitmq) diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/01_introduction.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/01_introduction.Rmd index fcaad0b7258..4ed5872d234 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/01_introduction.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/01_introduction.Rmd @@ -1,8 +1,8 @@ -## Introduction to Docker? {#docker-intro} +## Introduction to Docker {#docker-intro} * [What is Docker](#what-is-docker) * [Working with Docker](#working-with-docker) -* [`docker-compose`]{#docker-compose} +* [`docker-compose`](#docker-compose) ### What is Docker? {#what-is-docker} diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/03_architecture.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/03_architecture.Rmd index 2eb10ce8c5a..6876509d38c 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/03_architecture.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/03_architecture.Rmd @@ -240,7 +240,7 @@ yaml::write_yaml(dc_yaml$services["pecan"], stdout()) Its Dockerfile ships with the PEcAn source code, in [`docker/web/Dockerfile`](https://github.com/PecanProject/pecan/blob/develop/docker/web/Dockerfile). -In terms of [actively developing PEcAn using Docker](#pecan-docker-develop), this is the service to modify when making changes to the web interface (i.e. PHP, HTML, and JavaScript code located in the PEcAn `web` directory). +In terms of [actively developing PEcAn using Docker](#docker-local-devel), this is the service to modify when making changes to the web interface (i.e. PHP, HTML, and JavaScript code located in the PEcAn `web` directory). ### `executor` {#pecan-dc-executor} @@ -257,7 +257,7 @@ Its Dockerfile ships with the PEcAn source code, in [`docker/executor/Dockerfile Its image is built on top of the `pecan/base` image ([`docker/base/Dockerfile`](https://github.com/PecanProject/pecan/blob/develop/docker/base/Dockerfile)), which contains the actual PEcAn source. To facilitate caching, the `pecan/base` image is itself built on top of the `pecan/depends` image ([`docker/depends/Dockerfile`](https://github.com/PecanProject/pecan/blob/develop/docker/depends/Dockerfile)), a large image that contains an R installation and PEcAn's many system and R package dependencies (which usually take ~30 minutes or longer to install from scratch). -In terms of [actively developing PEcAn using Docker](#pecan-docker-develop), this is the service to modify when making changes to the PEcAn R source code. +In terms of [actively developing PEcAn using Docker](#docker-local-devel), this is the service to modify when making changes to the PEcAn R source code. Note that, unlike changes to the `web` image's PHP code, changes to the R source code do not immediately propagate to the PEcAn container; instead, you have to re-compile the code by running `make` inside the container. ### `monitor` {#pecan-dc-monitor} diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/05_building_images.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/05_building_images.Rmd index 4ccbd1dc8d6..36aca4bb10a 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/05_building_images.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/05_building_images.Rmd @@ -4,7 +4,7 @@ The only other section on this page is: [Local development and testing with Docker](#docker-local-devel) -For general use, it is sufficient to use the pre-built PEcAn images hosted on [Docker Hub](https://hub.docker.com/r/pecan/) (see [Docker quickstart](04_docker/02_quickstart.html)). +For general use, it is sufficient to use the pre-built PEcAn images hosted on [Docker Hub](https://hub.docker.com/r/pecan/) (see [Docker quickstart](#docker-quickstart)). However, there are cases where it makes sense to re-build the Docker images locally. The following is a list of PEcAn-specific images and reasons why you would want to rebuild them locally: diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/07_migrate.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/07_migrate.Rmd index 943a0dc7ec0..08418f4fc16 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/07_migrate.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/07_migrate.Rmd @@ -1,6 +1,6 @@ ## Migrating PEcAn from VM to Docker {#docker-migrate} -This document assumes you have read through the [Introduction to Docker](04_docker/01_introduction.html) as well as [Docker quickstart](04_docker/02_quickstart.html)running on the VM._ +This document assumes you have read through the [Introduction to Docker](#docker-intro) as well as the [Docker quickstart](#docker-quickstart), and that you have a working PEcAn installation running on the VM. This document will slowly replace each of the components with the appropriate docker images. At then end of this document you should be able to use the docker-compose command to bring up the full docker stack as if you had started with this origianally. diff --git a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/08_pecan_api.Rmd b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/08_pecan_api.Rmd index 054b0537a4d..565ccbca006 100644 --- a/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/08_pecan_api.Rmd +++ b/book_source/02_demos_tutorials_workflows/05_developer_workflows/04_docker/08_pecan_api.Rmd @@ -1,6 +1,6 @@ ## The PEcAn Docker API {#pecan-api} -If you have a running instance of Dockerized PEcAn (or other setup where PEcAn workflows are submitted via [RabbitMQ](09_rabbitmq.html)), +If you have a running instance of Dockerized PEcAn (or other setup where PEcAn workflows are submitted via [RabbitMQ](#rabbitmq)), you have the option of running and managing PEcAn workflows using the `pecanapi` package. For more details, see the `pecanapi` [package vignette](https://github.com/PecanProject/pecan/blob/develop/api/vignettes/pecanapi.Rmd) and function-level documentation. diff --git a/book_source/03_topical_pages/12_troubleshooting-pecan.Rmd b/book_source/03_topical_pages/12_troubleshooting-pecan.Rmd index d528dc21219..a621653fa4a 100755 --- a/book_source/03_topical_pages/12_troubleshooting-pecan.Rmd +++ b/book_source/03_topical_pages/12_troubleshooting-pecan.Rmd @@ -25,7 +25,7 @@ When troubleshooting PEcAn issues: - [Workflow failures](#workflow-failures) - [Database issues](#database-issues) - [Model errors](#model-errors) -- [Docker-related problems](#docker-issues) +- [Docker-related problems](#docker-troubleshooting) - [Debugging](#debugging) diff --git a/book_source/03_topical_pages/93_installation/00_installation_index.Rmd b/book_source/03_topical_pages/93_installation/00_installation_index.Rmd index 323179604c5..46e8936d6d5 100644 --- a/book_source/03_topical_pages/93_installation/00_installation_index.Rmd +++ b/book_source/03_topical_pages/93_installation/00_installation_index.Rmd @@ -5,4 +5,4 @@ requirements for running PEcAn outside of Docker-based setups. Most users should follow the standard installation guide unless custom configurations are required. -This chapter contains details about installing and maintaining the uncontainerized version of PEcAn on a virtual machine or a server. If you are running PEcAn inside of Docker, many of the particulars will be different and you should refer to the [docker](developer-workflows/docker-index.html) chapter instead of this one. +This chapter contains details about installing and maintaining the uncontainerized version of PEcAn on a virtual machine or a server. If you are running PEcAn inside of Docker, many of the particulars will be different and you should refer to the [docker](#docker-index) chapter instead of this one.