Merge pull request #4460 from dokku/4219-registry-plugin

Implement registry plugin

docs/advanced-usage/registry-management.md

@@ -0,0 +1,126 @@
+# Registry Management
+
+> New as of 0.25.0
+
+```
+registry:login [--password-stdin] <server> <username> [<password>] # Login to a docker registry
+registry:report [<app>] [<flag>]                                   # Displays a registry report for one or more apps
+registry:set <app> <key> (<value>)                                 # Set or clear a registry property for an app
+```
+
+The registry plugin enables interacting with remote registries, which is useful when either deploying images via `git:from-image` or when interacting with custom schedulers to deploy built image artifacts.
+
+## Usage
+
+### Logging into a registry
+
+The `registry:login` command can be used to log into a docker registry. The following are examples for logging into various common registries:
+
+```shell
+# hub.docker.com
+dokku registry:login docker.io $USERNAME $PASSWORD
+
+# digitalocean
+# the username and password are both defined as the same api token
+dokku registry:login registry.digitalocean.com $DIGITALOCEAN_API_TOKEN $DIGITALOCEAN_API_TOKEN
+
+# github container registry
+# see the following link for information on retrieving a personal access token
+#   https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images#authenticating-to-github-container-registry
+dokku registry:login ghcr.io $USERNAME $REGISTRY_PAT_TOKEN
+
+# quay
+# a robot user may be used to login
+dokku registry:login quay.io $USERNAME $PASSWORD
+```
+
+For security reasons, the password may also be specified as stdin by specifying the `--password-stdin` flag. This is supported regardless of the registry being logged into.
+
+```shell
+echo "$PASSWORD" | dokku registry:login --password-stdin docker.io $USERNAME
+```
+
+For certain Docker registries - such as Amazon ECR or Google's GCR registries - users may instead wish to use a docker credential helper to automatically authenticate against a server; please see the documentation regarding the credential helper in question for further setup instructions.
+
+### Setting a remote server
+
+To specify a remote server registry for pushes, set the `server` property via the `registry:set` command. The default value for this property is empty string. Setting the value to `docker.io` or `hub.docker.com` will result in the computed value being empty string (as that is the default, implicit registry), while any non-zero length value will have a `/` appended to it if there is not one already.
+
+```shell
+dokku registry:set node-js-app server docker.io
+```
+
+This property can be set for a single app or globally via the `--global` flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is empty string.
+
+```shell
+dokku registry:set --global server docker.io
+```
+
+Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.
+
+```shell
+# per-app
+dokku registry:set node-js-app server
+
+# globally
+dokku registry:set --global server
+```
+
+The following are the values that should be used for common remote servers:
+
+- Amazon Elastic Container Registry:
+  - value: `$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/`
+  - notes: The `$AWS_ACCOUNT_ID` and `$AWS_REGION` should match the values for your account and region, respectively. Additionally, an IAM profile that allows `push` access to the repository specified by `image-repo` should be attached to your Dokku server.
+- Azure Container Registry:
+  - value `$REGISTRY_NAME.azurecr.io/`
+  - notes: The `$AKS_REGISTRY_NAME` should match the name of the registry created on your account.
+- Docker Hub:
+  - value: `docker.io/`
+  - notes: Requires owning the namespace used in the `image-repo` value.
+- Digitalocean:
+  - value: `registry.digitalocean.com/`
+  - notes: Requires setting the correct `image-repo` value for your registry.
+- Github Container Registry:
+  - value: `ghcr.io/`
+  - notes: Requires that the authenticated user has access to the namespace used in the `image-repo` value.
+- Quay.io:
+  - value: `quay.io/`
+
+### Specifying an image repository name
+
+By default, Dokku uses the value `dokku/$APP_NAME` as the image repository that is pushed and deployed. For certain registries, the `dokku` namespace may not be available to your user. In these cases, the value can be set by changing the value of the `image-repo` property via the `registry:set` command.
+
+```shell
+dokku registry:set node-js-app image-repo my-awesome-prefix/node-js-app
+```
+
+Setting the property value to an empty string will reset the value to the system default. Resetting the value has to be done per-app.
+
+```shell
+# per-app
+dokku registry:set node-js-app push-on-release
+```
+
+### Pushing images on build
+
+To push the image on release, set the `push-on-release` property to `true` via the `registry:set` command. The default value for this property is `false`. Setting the property to `true` will result in the imag being tagged with an ID that is incremented with every release. This tag will be what is used for running app code.
+
+```shell
+dokku registry:set node-js-app push-on-release true
+```
+
+This property can be set for a single app or globally via the `--global` flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is `false`.
+
+```shell
+dokku registry:set --global push-on-release true
+```
+
+Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.
+
+```shell
+# per-app
+dokku registry:set node-js-app push-on-release
+
+# globally
+dokku registry:set --global push-on-release
+```

docs/appendices/0.25.0-migration-guide.md

@@ -1,16 +1,29 @@
 # 0.25.0 Migration Guide
 
-## Changes
+## Registry Plugin
+
+The [dokku-registry](https://github.com/dokku/dokku-registry) plugin is now built-in. This comes with a few changes:
+
+- Builder plugins should call `post-release-builder` at the end of the build.
+- The `push` and `pull` command are not implemented. Users wishing to deploy a remote image should use `git:from-image`. Image pushing is not available at this time.
+- At this time, remote docker repositories are not automatically created for AWS, and users must create those repositories for their applications as necessary. This may be implemented in the future.
+- Docker images are only pushed when configured to do so. See the [registry management documentation](/docs/deployment/registry-management.md) for more details.
+
+## Other
+
+### Changes
 
 - The network plugin can now set an `initial-network` for all containers on creation. This is a replacement for specifying the `--network` flag via the `docker-options` plugin. Please see the [network documentation](/docs/networking/network.md#attaching-an-app-to-a-network) for more information.
 - The `dokku run` command now always removes the ephemeral container on exit. Users that need a persistent container should instead specify a `console` process type in their `Procfile` specifying an available shell (usually either `bash` or `sh`) and scale that container appropriately.
+- The `pre-deploy` plugin trigger is now called internally by Dokku. Scheduler plugins should avoid calling this trigger, as any image changes introduced by subsequent trigger calls will be ignored.
 
-## Deprecations
+### Deprecations
 
 - In previous versions of Dokku, the only way to specify a custom `Dockerfile` was to use the `docker-options` plugin to set the `--file` flag for a docker build. As of 0.25.0, the `builder-dockerfile:set` command should be used instead, as outlined in the [docs here](/docs/deployment/builders/dockerfiles.md#changingthe-dockerfile-location). Usage of the old method should be migrated to the new method.
 - The `--rm` and ``--rm-container` flags may be specified but no longer have any effect on `dokku run`.
 - The `--detach` flag is deprecated in favor of the `run:detached` command.
 - The `DOKKU_SCALE` file is deprecated. Please see the [process management documentation](/docs/processes/process-management.md#manually-managing-process-scaling) for more information on it's replacement with the `formations` key of the `app.json` file.
+- The hooks `post-release-buildpack`, `post-release-dockerfile`, and `post-release-pack` are deprecated in favor of `post-release-builder`. See the [plugin triggers documentation](https://dokku.com/docs/development/plugin-triggers/#post-release-builder) for more details.
 
 ## Removals
 

docs/development/plugin-triggers.md

@@ -1345,8 +1345,28 @@ APP="$1"
 haproxy-build-config "$APP"
 ```
 
+### `post-release-builder`
+
+> Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.
+
+- Description: Invokes a command after the build process is complete.
+- Invoked by: builder plugins
+- Arguments: `$BUILDER_TYPE $APP $IMAGE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+BUILDER_TYPE="$1"; APP="$2"; IMAGE=$3
+
+# TODO
+```
+
 ### `post-release-buildpack`
 
+> Warning: Deprecated, please use `post-release-builder` instead
 > Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.
 
 - Description: Allows you to run commands after environment variables are set for the release step of the deploy. Only applies to apps using buildpacks.
@@ -1366,6 +1386,8 @@ APP="$1"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)
 
 ### `post-release-pack`
 
+> Warning: Deprecated, please use `post-release-builder` instead
+
 > Warning: The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
@@ -1388,6 +1410,8 @@ APP="$1"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)
 
 ### `post-release-dockerfile`
 
+> Warning: Deprecated, please use `post-release-builder` instead
+
 > Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.
 
 - Description: Allows you to run commands after environment variables are set for the release step of the deploy. Only applies to apps using a dockerfile.

docs/template.html

@@ -150,6 +150,7 @@
             <a href="/{{NAME}}/advanced-usage/backup-recovery/" class="list-group-item">Backup and Recovery</a>
             <a href="/{{NAME}}/advanced-usage/deployment-tasks/" class="list-group-item">Deployment Tasks</a>
             <a href="/{{NAME}}/advanced-usage/docker-options/" class="list-group-item">Docker Container Options</a>
+            <a href="/{{NAME}}/advanced-usage/registry-management/" class="list-group-item">Docker Registry Management</a>
             <a href="/{{NAME}}/advanced-usage/event-logs/" class="list-group-item">Event Logs</a>
             <a href="/{{NAME}}/advanced-usage/persistent-storage/" class="list-group-item">Persistent Storage</a>
             <a href="/{{NAME}}/advanced-usage/plugin-management/" class="list-group-item">Plugin Management</a>

docs/viewdocs.json

@@ -38,6 +38,9 @@
     "dokku-events-logs": "advanced-usage/event-logs/",
     "dokku-storage": "advanced-usage/persistent-storage/",
 
+    "advanced-usage/schedulers/alternate-schedulers": "deployment/schedulers/alternate-schedulers",
+    "advanced-usage/schedulers/docker-local": "deployment/schedulers/docker-local",
+
     "community/tutorials/deploying-with-gitlab-ci": "deployment/continuous-integration/gitlab-ci/",
 
     "plugins": "community/plugins/"