diff --git a/docs/deployment/methods/archive.md b/docs/deployment/methods/archive.md new file mode 100644 index 00000000000..325acfb594c --- /dev/null +++ b/docs/deployment/methods/archive.md @@ -0,0 +1,34 @@ +# Deploying from a remote tarball or zip + +## Initializing an app repository from an archive file + +> [!IMPORTANT] +> New as of 0.24.0 + +A Dokku app repository can be initialized or updated from the contents of an archive file via the `git:from-archive` command. This is an excellent way of tracking changes when deploying pre-built binary archives, such as java jars or go binaries. This can also be useful when deploying directly from a GitHub repository at a specific commit. + +```shell +dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar +``` + +In the above example, Dokku will build the app as if the repository contained the extracted contents of the specified archive file. + +Triggering a build with the same archive file multiple times will result in Dokku exiting `0` early as there will be no changes detected. + +The `git:from-archive` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively. + +```shell +dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar "Camila" "camila@example.com" +``` + +The default archive type is always set to `.tar`. To use a different archive type, specify the `--archive-type` flag. Failure to do so will result in a failure to extract the archive. + +```shell +dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip "Camila" "camila@example.com" +``` + +Finally, if the archive url is specified as `--`, the archive will be fetched from stdin. + +```shell +curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar | dokku git:from-archive node-js-app -- +``` diff --git a/docs/deployment/methods/git.md b/docs/deployment/methods/git.md index ef5d344b86f..7a9c4fce200 100644 --- a/docs/deployment/methods/git.md +++ b/docs/deployment/methods/git.md @@ -125,142 +125,6 @@ dokku git:set node-js-app keep-git-dir "" Please keep in mind that setting `keep-git-dir` to `true` may result in unstaged changes shown within the built container due to the build process generating application changes within the built app directory. -### Initializing an app repository from a docker image - -> [!IMPORTANT] -> New as of 0.24.0 - -A Dokku app repository can be initialized or updated from a Docker image via the `git:from-image` command. This command will either initialize the app repository or update it to include the specified Docker image via a `FROM` stanza. This is an excellent way of tracking changes when deploying only a given docker image, especially if deploying an image from a remote CI/CD pipeline. - -```shell -dokku git:from-image node-js-app dokku/node-js-getting-started:latest -``` - -In the above example, Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content: - -```Dockerfile -FROM dokku/node-js-getting-started:latest -``` - -If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using [build phase docker-options](/docs/advanced-usage/docker-options.md). - -Triggering a build with the same arguments multiple times will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command: - -```shell -# for images pushed to a remote registry -docker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME - -# for images built locally and not pushed to a registry -# use when the previous command output is empty -docker images --no-trunc --quiet $IMAGE_NAME -``` - -The resulting `git:from-image` call would then be: - -```shell -# where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 -dokku git:from-image node-js-app dokku/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 -``` - -The `git:from-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively. - -```shell -dokku git:from-image node-js-app dokku/node-js-getting-started:latest "Camila" "camila@example.com" -``` - -If the image is a private image that requires a docker login to access, the `registry:login` command should be used to log into the registry. See the [registry documentation](/docs/advanced-usage/registry-management.md#logging-into-a-registry) for more details on this process. - -Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds. - -```shell -dokku git:from-image --build-dir path/to/build node-js-app dokku/node-js-getting-started:latest "Camila" "camila@example.com" -``` - -See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys. - -### Initializing an app repository from an archive file - -> [!IMPORTANT] -> New as of 0.24.0 - -A Dokku app repository can be initialized or updated from the contents of an archive file via the `git:from-archive` command. This is an excellent way of tracking changes when deploying pre-built binary archives, such as java jars or go binaries. This can also be useful when deploying directly from a GitHub repository at a specific commit. - -```shell -dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar -``` - -In the above example, Dokku will build the app as if the repository contained the extracted contents of the specified archive file. - -Triggering a build with the same archive file multiple times will result in Dokku exiting `0` early as there will be no changes detected. - -The `git:from-archive` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively. - -```shell -dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar "Camila" "camila@example.com" -``` - -The default archive type is always set to `.tar`. To use a different archive type, specify the `--archive-type` flag. Failure to do so will result in a failure to extract the archive. - -```shell -dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip "Camila" "camila@example.com" -``` - -Finally, if the archive url is specified as `--`, the archive will be fetched from stdin. - -```shell -curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar | dokku git:from-archive node-js-app -- -``` - -### Initializing an app repository from a remote image without a registry - -> [!IMPORTANT] -> New as of 0.30.0 - -A Dokku app repository can be initialized or updated from the contents of an image archive tar file via the `git:load-image` command. This method can be used when a Docker Registry is unavailable to act as an intermediary for storing an image, such as when building an image in CI and deploying directly from that image. - -```shell -docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app dokku/node-js-getting-started:latest -``` - -In the above example, we are saving the image to a tar file via `docker image save`, streaming that to the Dokku host, and then running `git:load-image` on the incoming stream. Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content: - -```Dockerfile -FROM dokku/node-js-getting-started:latest -``` - -When deploying an app via `git:load-image`, it is highly recommended to use a unique image tag when building the image. Not doing so will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command: - -```shell - -# for images pushed to a remote registry -docker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME - -# for images built locally and not pushed to a registry -# use when the previous command output is empty -docker images --no-trunc --quiet $IMAGE_NAME -``` - -The resulting `git:load-image` call would then be: - -```shell -# where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 -docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app dokku/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 -``` - -The `git:load-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively. - -```shell -docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app dokku/node-js-getting-started:latest "Camila" "camila@example.com" -``` - -Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds. - -```shell -docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image --build-dir path/to/build node-js-app dokku/node-js-getting-started:latest "Camila" "camila@example.com" -``` - -See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys. - ### Initializing an app repository from a remote repository > [!IMPORTANT] diff --git a/docs/deployment/methods/image.md b/docs/deployment/methods/image.md new file mode 100644 index 00000000000..aca831f9b38 --- /dev/null +++ b/docs/deployment/methods/image.md @@ -0,0 +1,104 @@ +# Docker Image Deployment + +## Initializing an app repository from a docker image + +> [!IMPORTANT] +> New as of 0.24.0 + +A Dokku app repository can be initialized or updated from a Docker image via the `git:from-image` command. This command will either initialize the app repository or update it to include the specified Docker image via a `FROM` stanza. This is an excellent way of tracking changes when deploying only a given docker image, especially if deploying an image from a remote CI/CD pipeline. + +```shell +dokku git:from-image node-js-app my-registry/node-js-getting-started:latest +``` + +In the above example, Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content: + +```Dockerfile +FROM my-registry/node-js-getting-started:latest +``` + +If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using [build phase docker-options](/docs/advanced-usage/docker-options.md). + +Triggering a build with the same arguments multiple times will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command: + +```shell +# for images pushed to a remote registry +docker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME + +# for images built locally and not pushed to a registry +# use when the previous command output is empty +docker images --no-trunc --quiet $IMAGE_NAME +``` + +The resulting `git:from-image` call would then be: + +```shell +# where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 +dokku git:from-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 +``` + +The `git:from-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively. + +```shell +dokku git:from-image node-js-app my-registry/node-js-getting-started:latest "Camila" "camila@example.com" +``` + +If the image is a private image that requires a docker login to access, the `registry:login` command should be used to log into the registry. See the [registry documentation](/docs/advanced-usage/registry-management.md#logging-into-a-registry) for more details on this process. + +Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds. + +```shell +dokku git:from-image --build-dir path/to/build node-js-app domy-registrykku/node-js-getting-started:latest "Camila" "camila@example.com" +``` + +See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys. + +## Initializing an app repository from a remote image without a registry + +> [!IMPORTANT] +> New as of 0.30.0 + +A Dokku app repository can be initialized or updated from the contents of an image archive tar file via the `git:load-image` command. This method can be used when a Docker Registry is unavailable to act as an intermediary for storing an image, such as when building an image in CI and deploying directly from that image. + +```shell +docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest +``` + +In the above example, we are saving the image to a tar file via `docker image save`, streaming that to the Dokku host, and then running `git:load-image` on the incoming stream. Dokku will build the app as if the repository contained _only_ a `Dockerfile` with the following content: + +```Dockerfile +FROM my-registry/node-js-getting-started:latest +``` + +When deploying an app via `git:load-image`, it is highly recommended to use a unique image tag when building the image. Not doing so will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command: + +```shell + +# for images pushed to a remote registry +docker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME + +# for images built locally and not pushed to a registry +# use when the previous command output is empty +docker images --no-trunc --quiet $IMAGE_NAME +``` + +The resulting `git:load-image` call would then be: + +```shell +# where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 +docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673 +``` + +The `git:load-image` command can optionally take a git `user.name` and `user.email` argument (in that order) to customize the author. If the arguments are left empty, they will fallback to `Dokku` and `automated@dokku.sh`, respectively. + +```shell +docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest "Camila" "camila@example.com" +``` + +Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds. + +```shell +docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image --build-dir path/to/build node-js-app my-registry/node-js-getting-started:latest "Camila" "camila@example.com" +``` + +See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys. diff --git a/docs/template.html b/docs/template.html index 819b7453610..c456d89b5e1 100644 --- a/docs/template.html +++ b/docs/template.html @@ -153,6 +153,8 @@ Deployment Methods Git Deployment + Docker Image Deployment + Archive Deployment Configuration diff --git a/docs/viewdocs.json b/docs/viewdocs.json index fbbfd817c19..bc0878c6684 100644 --- a/docs/viewdocs.json +++ b/docs/viewdocs.json @@ -16,10 +16,10 @@ "deployment/methods/cloud-native-buildpacks": "deployment/builders/cloud-native-buildpacks/", "deployment/methods/dockerfiles": "deployment/builders/dockerfiles/", "deployment/methods/herokuish-buildpacks": "deployment/builders/herokuish-buildpacks/", - "deployment/images": "deployment/methods/git/#initializing-an-app-repository-from-a-docker-image", - "deployment/tar": "deployment/methods/git/#initializing-an-app-repository-from-an-archive-file", - "deployment/methods/images": "deployment/methods/git/#initializing-an-app-repository-from-a-docker-image", - "deployment/methods/tar": "deployment/methods/git/#initializing-an-app-repository-from-an-archive-file", + "deployment/images": "deployment/methods/image/", + "deployment/tar": "deployment/methods/archive/", + "deployment/methods/images": "deployment/methods/image/", + "deployment/methods/tar": "deployment/methods/archive/", "configuration-management": "configuration/environment-variables/", "deployment/ssl-configuration": "configuration/ssl/", "configuration/nginx": "networking/proxies/nginx/",