dokku · josegonzalez · Jul 1, 2023 · Jul 1, 2023
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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: