From 14557c148aa941b9b0842710c88359e7a640d833 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Thu, 29 Apr 2021 22:00:05 +0300 Subject: [PATCH 1/4] Rename Docker Cloud -> Docker Hub --- docs/contributing/stacks.md | 12 ++++++------ docs/maintaining/tasks.md | 24 ++++++++++++------------ docs/using/selecting.md | 2 +- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/contributing/stacks.md b/docs/contributing/stacks.md index a997ba6a..338b263a 100644 --- a/docs/contributing/stacks.md +++ b/docs/contributing/stacks.md @@ -9,7 +9,7 @@ Following these steps will: `jupyter/minimal-notebook` image. 2. Configure GitHub Actions to build and test your image when users submit pull requests to your repository. -3. Configure Docker Cloud to build and host your images for others to use. +3. Configure Docker Hub to build and host your images for others to use. 4. Update the [list of community stacks](../using/selecting.html#community-stacks) in this documentation to include your image. This approach mirrors how we build and share the core stack images. Feel free to follow it or pave @@ -38,8 +38,8 @@ of the Docker image name after the slash. stack_name [my-jupyter-stack]: ``` -Enter the user or organization name under which this stack will reside on Docker Cloud / Hub. You -must have access to manage this Docker Cloud org to push images here and set up automated +Enter the user or organization name under which this stack will reside on Docker Hub. You +must have access to manage this Docker Hub organization to push images here and set up automated builds. ``` @@ -104,9 +104,9 @@ From there, you can click on the workflows on the left-hand side of the screen. 4. In the next screen, you will be able to see information about the workflow run and duration. If you click again on the button with the workflow name, you will see the logs for the workflow steps. ![Github actions workflow run screenshot](../static/../_static/github-actions-workflow.png) -## Configuring Docker Cloud +## Configuring Docker Hub -Now, configure Docker Cloud to build your stack image and push it to Docker Hub repository whenever +Now, configure Docker Hub to build your stack image and push it to Docker Hub repository whenever you merge a GitHub pull request to the master branch of your project. 1. Visit [https://hub.docker.com/](https://hub.docker.com/) and log in. @@ -144,7 +144,7 @@ to get a feel for what's possible and best practices. [Submit pull requests](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) to your project repository on GitHub. Ensure your image builds correctly on GitHub actions before merging to -master or main. Refer to Docker Cloud to build your master or main branch that you can `docker pull`. +master or main. Refer to Docker Hub to build your master or main branch that you can `docker pull`. ## Sharing Your Image diff --git a/docs/maintaining/tasks.md b/docs/maintaining/tasks.md index f3bbf438..e71e05dc 100644 --- a/docs/maintaining/tasks.md +++ b/docs/maintaining/tasks.md @@ -2,20 +2,20 @@ ## Merging Pull Requests -To build new images on Docker Cloud and publish them to the Docker Hub registry, do the following: +To build new images and publish them to the Docker Hub registry, do the following: 1. Make sure GitHub Actions status checks pas for the PR. 2. Merge the PR. -3. Monitor the Docker Cloud build status for each of the stacks, starting with - [jupyter/base-notebook](https://cloud.docker.com/app/jupyter/repository/docker/jupyter/base-notebook/general) +3. Monitor the Docker Hub build status for each of the stacks, starting with + [jupyter/base-notebook](https://hub.docker.com/app/jupyter/repository/docker/jupyter/base-notebook/general) and ending with - [jupyter/all-spark-notebook](https://cloud.docker.com/app/jupyter/repository/docker/jupyter/all-spark-notebook/general). + [jupyter/all-spark-notebook](https://hub.docker.com/app/jupyter/repository/docker/jupyter/all-spark-notebook/general). See the [stack hierarchy diagram](../using/selecting.html#image-relationships) for the current, complete build order. 4. Manually click the retry button next to any build that fails to resume that build and any dependent builds. 5. Try to avoid merging another PR to master until all outstanding builds complete. There's no way - at present to propagate the git SHA to build through the Docker Cloud build trigger API. Every + at present to propagate the git SHA to build through the Docker Hub build trigger API. Every build trigger works off of master HEAD. ## Updating the Ubuntu Base Image @@ -26,7 +26,7 @@ update the pinned SHA in the Submit it as a regular PR and go through the build process. Expect the build to take a while to complete: every image layer will rebuild. -## Adding a New Core Image to Docker Cloud +## Adding a New Core Image to Docker Hub When there's a new stack definition, do the following before merging the PR with the new stack: @@ -34,12 +34,12 @@ When there's a new stack definition, do the following before merging the PR with [in the documentation](https://github.com/jupyter/docker-stacks/blob/master/docs/using/selecting.md#image-relationships). The image links to the [blockdiag source](http://interactive.blockdiag.com/) used to create it. 2. Ensure the PR updates the Makefile which is used to build the stacks in order on GitHub Actions. -3. Create a new repository in the `jupyter` org on Docker Cloud named after the stack folder in the +3. Create a new repository in the `jupyter` org on Docker Hub named after the stack folder in the git repo. 4. Grant the `stacks` team permission to write to the repo. 5. Click _Builds_ and then _Configure Automated Builds_ for the repository. 6. Select `jupyter/docker-stacks` as the source repository. -7. Choose _Build on Docker Cloud's infrastructure using a Small node_ unless you have reason to +7. Choose _Build on Docker Hub's infrastructure using a Small node_ unless you have reason to believe a bigger host is required. 8. Update the _Build Context_ in the default build rule to be `/`. 9. Toggle _Autobuild_ to disabled unless the stack is a new root stack (e.g., like @@ -62,18 +62,18 @@ When there's a new stack definition, do the following before merging the PR with ## Adding a New Maintainer Account -1. Visit https://cloud.docker.com/app/jupyter/team/stacks/users -2. Add the maintainer's Docker Cloud username. +1. Visit https://hub.docker.com/app/jupyter/team/stacks/users +2. Add the maintainer's Docker Hub username. 3. Visit https://github.com/orgs/jupyter/teams/docker-image-maintainers/members 4. Add the maintainer's GitHub username. ## Pushing a Build Manually -If automated builds on Docker Cloud have got you down, do the following to push a build manually: +If automated builds on Docker Hub have got you down, do the following to push a build manually: 1. Clone this repository. 2. Check out the git SHA you want to build and publish. -3. `docker login` with your Docker Hub/Cloud credentials. +3. `docker login` with your Docker Hub credentials. 4. Run `make retry/release-all`. ## Enabling a New Doc Language Translation diff --git a/docs/using/selecting.md b/docs/using/selecting.md index bda8ef0b..76270d90 100644 --- a/docs/using/selecting.md +++ b/docs/using/selecting.md @@ -174,7 +174,7 @@ diagram](../images/inherit.svg)](http://interactive.blockdiag.com/?compression=d Pull requests to the `jupyter/docker-stacks` repository trigger builds of all images on GitHub Actions. These images are for testing purposes only and are not saved for use. When pull requests -merge to master, all images rebuild on Docker Cloud and become available to `docker pull` from +merge to master, all images rebuild on Docker Hub and become available to `docker pull` from Docker Hub. ### Versioning From 6bef0e33073c80d99c9d58a19bc1bb987ca472fe Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 7 May 2021 02:03:24 +0300 Subject: [PATCH 2/4] Improve docs for GitHub Actions --- docs/maintaining/tasks.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/maintaining/tasks.md b/docs/maintaining/tasks.md index a7838ba8..cfb6f817 100644 --- a/docs/maintaining/tasks.md +++ b/docs/maintaining/tasks.md @@ -4,19 +4,13 @@ To build new images and publish them to the Docker Hub registry, do the following: -1. Make sure GitHub Actions status checks pas for the PR. +1. Make sure GitHub Actions status checks pass for the PR. 2. Merge the PR. -3. Monitor the Docker Hub build status for each of the stacks, starting with - [jupyter/base-notebook](https://hub.docker.com/app/jupyter/repository/docker/jupyter/base-notebook/general) - and ending with - [jupyter/all-spark-notebook](https://hub.docker.com/app/jupyter/repository/docker/jupyter/all-spark-notebook/general). - See the [stack hierarchy diagram](../using/selecting.html#image-relationships) for the current, - complete build order. -4. Manually click the retry button next to any build that fails to resume that build and any - dependent builds. -5. Try to avoid merging another PR to master until all outstanding builds complete. There's no way - at present to propagate the git SHA to build through the Docker Hub build trigger API. Every - build trigger works off of master HEAD. +3. Monitor the merge commit GitHub Actions status. + **Note**: we think, GitHub Actions are quite reliable, so please, investigate, if some error occurs. + The process of building docker images in PRs is exactly the same for master branch, except there is a push step in master. +4. Try to avoid merging another PR to master until all pending builds complete. This way you will know which commit + might have broken the build and also have correct tags for moving tags (like `python` version). ## Updating the Ubuntu Base Image @@ -74,7 +68,7 @@ If automated builds on Docker Hub have got you down, do the following to push a 1. Clone this repository. 2. Check out the git SHA you want to build and publish. 3. `docker login` with your Docker Hub credentials. -4. Run `make retry/release-all`. +4. Run `make push-all`. ## Enabling a New Doc Language Translation From 408a7938130f04916d4cb39e746facb32bf1fe7b Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 7 May 2021 02:15:47 +0300 Subject: [PATCH 3/4] Improve text --- docs/maintaining/tasks.md | 33 ++++++--------------------------- 1 file changed, 6 insertions(+), 27 deletions(-) diff --git a/docs/maintaining/tasks.md b/docs/maintaining/tasks.md index cfb6f817..d04b6429 100644 --- a/docs/maintaining/tasks.md +++ b/docs/maintaining/tasks.md @@ -8,7 +8,7 @@ To build new images and publish them to the Docker Hub registry, do the followin 2. Merge the PR. 3. Monitor the merge commit GitHub Actions status. **Note**: we think, GitHub Actions are quite reliable, so please, investigate, if some error occurs. - The process of building docker images in PRs is exactly the same for master branch, except there is a push step in master. + The process of building docker images in PRs is exactly the same after merging to master, except there is an additional `push` step. 4. Try to avoid merging another PR to master until all pending builds complete. This way you will know which commit might have broken the build and also have correct tags for moving tags (like `python` version). @@ -27,32 +27,11 @@ When there's a new stack definition, do the following before merging the PR with 1. Ensure the PR includes an update to the stack overview diagram [in the documentation](https://github.com/jupyter/docker-stacks/blob/master/docs/using/selecting.md#image-relationships). The image links to the [blockdiag source](http://interactive.blockdiag.com/) used to create it. -2. Ensure the PR updates the Makefile which is used to build the stacks in order on GitHub Actions. -3. Create a new repository in the `jupyter` org on Docker Hub named after the stack folder in the +2. Ensure the PR updates the [Makefile](../../Makefile) which is used to build the stacks in order on GitHub Actions. +3. Ensure necessary tags / manifests are added for the new image in the [tagging](../../tagging) folder. +4. Create a new repository in the `jupyter` org on Docker Hub named after the stack folder in the git repo. -4. Grant the `stacks` team permission to write to the repo. -5. Click _Builds_ and then _Configure Automated Builds_ for the repository. -6. Select `jupyter/docker-stacks` as the source repository. -7. Choose _Build on Docker Hub's infrastructure using a Small node_ unless you have reason to - believe a bigger host is required. -8. Update the _Build Context_ in the default build rule to be `/`. -9. Toggle _Autobuild_ to disabled unless the stack is a new root stack (e.g., like - `jupyter/base-notebook`). -10. If the new stack depends on the build of another stack in the hierarchy: - 1. Hit _Save_ and then click _Configure Automated Builds_. - 2. At the very bottom, add a build trigger named _Stack hierarchy trigger_. - 3. Copy the build trigger URL. - 4. Visit the parent repository _Builds_ page and click _Configure Automated Builds_. - 5. Add the URL you copied to the _NEXT_BUILD_TRIGGERS_ environment variable comma separated list - of URLs, creating that environment variable if it does not already exist. - 6. Hit _Save_. -11. If the new stack should trigger other dependent builds: - 1. Add an environment variable named _NEXT_BUILD_TRIGGERS_. - 2. Copy the build trigger URLs from the dependent builds into the _NEXT_BUILD_TRIGGERS_ comma - separated list of URLs. - 3. Hit _Save_. -12. Adjust other _NEXT_BUILD_TRIGGERS_ values as needed so that the build order matches that in the - stack hierarchy diagram. +5. Grant the `stacks` team permission to write to the repo. ## Adding a New Maintainer Account @@ -63,7 +42,7 @@ When there's a new stack definition, do the following before merging the PR with ## Pushing a Build Manually -If automated builds on Docker Hub have got you down, do the following to push a build manually: +If automated build in Github Actions have got you down, do the following to push a build manually: 1. Clone this repository. 2. Check out the git SHA you want to build and publish. From 86237e3d656a73207a27fcf641685ea7b09123f7 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 7 May 2021 02:23:16 +0300 Subject: [PATCH 4/4] Update docs/maintaining/tasks.md --- docs/maintaining/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maintaining/tasks.md b/docs/maintaining/tasks.md index d04b6429..9383de89 100644 --- a/docs/maintaining/tasks.md +++ b/docs/maintaining/tasks.md @@ -42,7 +42,7 @@ When there's a new stack definition, do the following before merging the PR with ## Pushing a Build Manually -If automated build in Github Actions have got you down, do the following to push a build manually: +If automated build in Github Actions has got you down, do the following to push a build manually: 1. Clone this repository. 2. Check out the git SHA you want to build and publish.