From 73f61b75d5efa9c6c93f736dbd00e6c48942b1ef Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 1 Jul 2023 08:58:43 -0400 Subject: [PATCH] docs: update docs to mention that files are extracted from source where source code is available Recent Dokku changes invalidate a bunch of docs around where files need to be placed in order for Dokku to respect them. This doc change clarifies where files are extracted from in cases where source code is available, which should hopefully make users less confused about how the system works. See https://railsnotes.xyz/blog/deploying-ruby-on-rails-with-dokku-redis-sidekiq-arm-docker-hetzner for the inspiration - I was reading through it and was like 'these docs are definitely incorrect...'. --- docs/advanced-usage/deployment-tasks.md | 7 ++++--- .../builders/cloud-native-buildpacks.md | 4 +++- docs/deployment/builders/dockerfiles.md | 18 ++++++++---------- docs/deployment/builders/lambda.md | 4 +++- docs/deployment/schedulers/docker-local.md | 8 ++------ docs/networking/proxies/nginx.md | 7 +++++-- docs/processes/process-management.md | 16 +++++++--------- docs/processes/scheduled-cron-tasks.md | 2 ++ 8 files changed, 34 insertions(+), 32 deletions(-) diff --git a/docs/advanced-usage/deployment-tasks.md b/docs/advanced-usage/deployment-tasks.md index f1c71d51c..f13550445 100644 --- a/docs/advanced-usage/deployment-tasks.md +++ b/docs/advanced-usage/deployment-tasks.md @@ -57,8 +57,11 @@ Please keep the above in mind when utilizing deployment tasks. When deploying a monorepo, it may be desirable to specify the specific path of the `app.json` file to use for a given app. This can be done via the `app-json:set` command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no `app.json` file. +For deploys via the `git:from-image` and `git:load-image` commands, the `app.json` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `app.json` extracted directly from the source code. Both cases will respect the configured `appjson-path` property value. + + ```shell -dokku app-json:set node-js-app appjson-path second-app.json +dokku app-json:set node-js-app appjson-path .dokku/app.json ``` The default value may be set by passing an empty value for the option: @@ -137,8 +140,6 @@ Dokku provides limited support for the `app.json` manifest from Heroku (document - `scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase. - `scripts.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase. -For buildpack-based deployments, the location of the `app.json` file should be at the root of your repository. Dockerfile-based app deploys should have the `app.json` in the configured `WORKDIR` directory; otherwise Dokku defaults to the buildpack app behavior of looking in `/app`. - > Warning: Any failed `app.json` deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers. The following is an example `app.json` file. Please note that only the `scripts.dokku.predeploy` and `scripts.dokku.postdeploy` tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted. diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index 85ba3e8c2..d4377b3dd 100644 --- a/docs/deployment/builders/cloud-native-buildpacks.md +++ b/docs/deployment/builders/cloud-native-buildpacks.md @@ -60,8 +60,10 @@ dokku builder:set node-js-app selected pack When deploying a monorepo, it may be desirable to specify the specific path of the `project.toml` file to use for a given app. This can be done via the `builder-pack:set` command. If a value other than `project.toml` is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no `project.toml`. +For deploys via the `git:from-image` and `git:load-image` commands, the `project.toml` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `project.toml` extracted directly from the source code. Both cases will respect the configured `projecttoml-path` property value. + ```shell -dokku builder-pack:set node-js-app projecttoml-path project2.toml +dokku builder-pack:set node-js-app projecttoml-path .dokku/project.toml ``` The default value may be set by passing an empty value for the option: diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index 915e3acab..7151cbc5f 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -38,6 +38,8 @@ dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP When deploying a monorepo, it may be desirable to specify the specific path of the `Dockerfile` file to use for a given app. This can be done via the `builder-dockerfile:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail. +For git push, `git:from-archive`, and `git:sync` workflows, the `Dockerfile` is extracted directly from the source code, respecting the configured `dockerfile-path` property value. + ```shell dokku builder-dockerfile:set node-js-app dockerfile-path Dockerfile2 ``` @@ -197,10 +199,7 @@ Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disa > New as of 0.5.0 You can also customize the run command using a `Procfile`, much like you would on Heroku or -with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types). -When you deploy your app, a Docker image will be built. The `Procfile` will be extracted from the image -(it must be in the folder defined in your `Dockerfile` as `WORKDIR` or `/app`) and the commands -in it will be passed to `docker run` to start your process(es). Here's an example `Procfile`: +with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types). The commands in your app's Procfile will be passed to `docker run` to start your process(es). Here's an example `Procfile`: ```Procfile web: bin/run-prod.sh @@ -216,12 +215,11 @@ COPY . ./ CMD ["bin/run-dev.sh"] ``` -When you deploy this app the `web` process will automatically be scaled to 1 and your Docker container -will be started basically using the command `docker run bin/run-prod.sh`. If you want to also run -a worker container for this app, you can run `dokku ps:scale worker=1` and a new container will be -started by running `docker run bin/run-worker.sh` (the actual `docker run` commands are a bit more -complex, but this is the basic idea). If you use an `ENTRYPOINT` in your `Dockerfile`, the lines -in your `Procfile` will be passed as arguments to the `ENTRYPOINT` script instead of being executed. +When the above example is deployed, the `web` process is started, with the command `bin/run-prod.sh` executed in the container. All other processes must be scaled up separately. If the app's `Dockerfile` contains an `ENTRYPOINT` directive, the command specified in the `Procfile` will be passed to that entrypoint script as an argument. + +See the [scaling apps documentation](/docs/processes/process-management.md#scaling-apps) for more information on how process scaling is performed. + +See the [app.json location documentation](/docs/processes/process-management.md#changing-the-procfile-location) for more information on where to place your `Procfile` file. ### Exposed ports diff --git a/docs/deployment/builders/lambda.md b/docs/deployment/builders/lambda.md index 1248f8fb9..692268c07 100644 --- a/docs/deployment/builders/lambda.md +++ b/docs/deployment/builders/lambda.md @@ -43,8 +43,10 @@ The `lambda` builder plugin delegates all build logic to [lambda-builder](https: When deploying a monorepo, it may be desirable to specify the specific path of the `lambda.yml` file to use for a given app. This can be done via the `builder-lambda:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail. +For deploys via the `git:from-image` and `git:load-image` commands, the `lambda.yml` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `lambda.yml` extracted directly from the source code. Both cases will respect the configured `lambdayml-path` property value. + ```shell -dokku builder-lambda:set node-js-app lambdayml-path lambda2.yml +dokku builder-lambda:set node-js-app lambdayml-path .dokku/lambda.yml ``` The default value may be set by passing an empty value for the option: diff --git a/docs/deployment/schedulers/docker-local.md b/docs/deployment/schedulers/docker-local.md index ec6e4523b..c55ad1345 100644 --- a/docs/deployment/schedulers/docker-local.md +++ b/docs/deployment/schedulers/docker-local.md @@ -82,12 +82,6 @@ Note that increasing the value of `parallel-schedule-count` may significantly im By default, Dokku will deploy one instance of a given process type at a time. This can be increased by customizing the `app.json` `formation` key to include a `max_parallel` key for the given process type. -An `app.json` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below. - -- Buildpacks: `/app/app.json` -- Dockerfile: `WORKDIR/app.json` or `/app.json` (if no working directory specified) -- Docker Image: `WORKDIR/app.json` or `/app.json` (if no working directory specified) - The `formation` key should be specified as follows in the `app.json` file: ```Procfile @@ -107,6 +101,8 @@ Omitting or removing the entry will result in parallelism for that process type Note that increasing the value of `max_parallel` may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server. +See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file. + ## Scheduler Interface The following sections describe implemented scheduler functionality for the `docker-local` scheduler. diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md index 1470736e6..1f6213f9f 100644 --- a/docs/networking/proxies/nginx.md +++ b/docs/networking/proxies/nginx.md @@ -329,14 +329,17 @@ Dokku uses a templating library by the name of [sigil](https://github.com/glider When deploying a monorepo, it may be desirable to specify the specific path of the `nginx.conf.sigil` file to use for a given app. This can be done via the `nginx:set` command. If a value is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no `nginx.conf.sigil`. +For deploys via the `git:from-image` and `git:load-image` commands, the `nginx.conf.sigil` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `nginx.conf.sigil` extracted directly from the source code. Both cases will respect the configured `nginx-conf-sigil-path` property value. + + ```shell -dokku nginx:set node-js-app nginx-conf-sigil-path dokku/nginx.conf.sigil +dokku nginx:set node-js-app nginx-conf-sigil-path .dokku/nginx.conf.sigil ``` This property can also be changed globally, which will take into effect if there is no value at the app level. ```shell -dokku nginx:set --global nginx-conf-sigil-path dokku/nginx.conf.sigil +dokku nginx:set --global nginx-conf-sigil-path .dokku/nginx.conf.sigil ``` In either case, the value can be reset by specifying an empty value. diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 56d5f161c..eb8af7458 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -133,13 +133,7 @@ dokku ps:scale --skip-deploy node-js-app web=1 > Using a `formation` key in an `app.json` file with _any_ `quantity` specified disables the ability to use `ps:scale` for scaling. All processes not specified in the `app.json` will have their process count set to zero. -An `app.json` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below. - -- Buildpacks: `/app/app.json` -- Dockerfile: `WORKDIR/app.json` or `/app.json` (if no working directory specified) -- Docker Image: `WORKDIR/app.json` or `/app.json` (if no working directory specified) - -The `formation` key should be specified as follows in the `app.json` file: +Users can also configure scaling within the codebase itself to manage process scaling. The `formation` key should be specified as follows in the `app.json` file: ```Procfile { @@ -154,7 +148,9 @@ The `formation` key should be specified as follows in the `app.json` file: } ``` -Removing the file will result in Dokku respecting the `ps:scale` command for setting scale values. The values set via the `app.json` file from a previous deploy will be respected. +Removing the `formation` key or removing the `app.json` file from your repository will result in Dokku respecting the `ps:scale` command for setting scale values. The values set via the `app.json` file from a previous deploy will be respected. + +See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file. #### The `web` process @@ -171,8 +167,10 @@ There are also a few other exceptions for the `web` process. When deploying a monorepo, it may be desirable to specify the specific path of the `Procfile` file to use for a given app. This can be done via the `ps:set` command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no `Procfile`. +For deploys via the `git:from-image` and `git:load-image` commands, the `Procfile` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `Procfile` extracted directly from the source code. Both cases will respect the configured `procfile-path` property value. + ```shell -dokku ps:set node-js-app procfile-path Procfile2 +dokku ps:set node-js-app procfile-path .dokku/Procfile ``` The default value may be set by passing an empty value for the option: diff --git a/docs/processes/scheduled-cron-tasks.md b/docs/processes/scheduled-cron-tasks.md index 8b6c5377f..f9dc11164 100644 --- a/docs/processes/scheduled-cron-tasks.md +++ b/docs/processes/scheduled-cron-tasks.md @@ -35,6 +35,8 @@ A cron entry takes the following properties: Zero or more cron commands can be specified per app. Cron entries are validated after the build artifact is created but before the app is deployed, and the cron schedule is updated during the post-deploy phase. +See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file. + #### Task Environment When running scheduled cron tasks, there are a few items to be aware of: