From 9930c0493d1446ddd6a3799b1bc5070ab0776836 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 3 Aug 2021 16:23:33 -0400 Subject: [PATCH] docs: update docs for new features --- docs/appendices/0.25.0-migration-guide.md | 16 +++++- docs/deployment/registry-management.md | 60 +++++++++++++++++++++++ docs/development/plugin-triggers.md | 24 +++++++++ 3 files changed, 98 insertions(+), 2 deletions(-) diff --git a/docs/appendices/0.25.0-migration-guide.md b/docs/appendices/0.25.0-migration-guide.md index 9ad58a916..f61892a97 100644 --- a/docs/appendices/0.25.0-migration-guide.md +++ b/docs/appendices/0.25.0-migration-guide.md @@ -1,16 +1,28 @@ # 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. -## 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 diff --git a/docs/deployment/registry-management.md b/docs/deployment/registry-management.md index c00712a4d..5e0da5623 100644 --- a/docs/deployment/registry-management.md +++ b/docs/deployment/registry-management.md @@ -42,6 +42,65 @@ echo "$PASSWORD" | dokku registry:login 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. + +```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`. @@ -65,3 +124,4 @@ dokku registry:set node-js-app push-on-release # globally dokku registry:set --global push-on-release ``` + diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index 1181a9cff..ed02204b2 100644 --- a/docs/development/plugin-triggers.md +++ b/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 `docker-args-process-build` 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 `docker-args-process-build` 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 `docker-args-process-build` 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.