From fe9a89024350671e351e2ab0cf615620155fec26 Mon Sep 17 00:00:00 2001 From: Flavio Poletti Date: Mon, 8 Jul 2024 08:12:17 +0200 Subject: [PATCH 1/2] Propose doc changes for procfile-path property --- docs/processes/process-management.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 839081734..747cb5b84 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -153,15 +153,20 @@ The `Procfile` also supports a special `release` command which acts in a similar #### Changing the `Procfile` location -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`. +The `Procfile` is expected to be found in a specific directory, depending on the deploy approach: -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. +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `procfile-path` property: ```shell dokku ps:set node-js-app procfile-path .dokku/Procfile ``` -The default value may be set by passing an empty value for the option: +The value is the path to the desired file *relative* to the base search directory (absolute paths don't work by design). If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `Procfile`. + +If a value is set, the default value may be set back by passing an empty value for the property: ```shell dokku ps:set node-js-app procfile-path From bbd5c039b538f3188125ae41720300b695bfd315 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 11 Aug 2024 03:52:48 -0400 Subject: [PATCH 2/2] docs: unify path setting docs for all custom files --- docs/advanced-usage/deployment-tasks.md | 9 ++++-- .../builders/cloud-native-buildpacks.md | 9 ++++-- docs/deployment/builders/dockerfiles.md | 11 ++++++-- docs/deployment/builders/lambda.md | 9 ++++-- docs/deployment/builders/nixpacks.md | 11 ++++++-- docs/networking/proxies/nginx.md | 28 +++++++++++++------ docs/processes/process-management.md | 4 +-- 7 files changed, 59 insertions(+), 22 deletions(-) diff --git a/docs/advanced-usage/deployment-tasks.md b/docs/advanced-usage/deployment-tasks.md index ee62d4f70..cf4907350 100644 --- a/docs/advanced-usage/deployment-tasks.md +++ b/docs/advanced-usage/deployment-tasks.md @@ -56,14 +56,19 @@ Please keep the above in mind when utilizing deployment tasks. ### Changing the `app.json` location -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. +The `app.json` is expected to be found in a specific directory, depending on the deploy approach: -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. +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `appjson-path` property: ```shell dokku app-json:set node-js-app appjson-path .dokku/app.json ``` +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `app.json`. + The default value may be set by passing an empty value for the option: ```shell diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index 1a30cf704..9381d548e 100644 --- a/docs/deployment/builders/cloud-native-buildpacks.md +++ b/docs/deployment/builders/cloud-native-buildpacks.md @@ -62,14 +62,19 @@ dokku builder:set node-js-app selected pack ### Changing the `project.toml` location -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`. +The `project.toml` is expected to be found in a specific directory, depending on the deploy approach: -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. +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `projecttoml-path` property: ```shell dokku builder-pack:set node-js-app projecttoml-path .dokku/project.toml ``` +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `project.toml`. + The default value may be set by passing an empty value for the option: ```shell diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index 71ead308c..38dc9bf13 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -37,14 +37,19 @@ dokku ports:clear node-js-app > The previous method to perform this - via `docker-options:add` - should be removed in favor of the `builder-dockerfile:set` command outlined here. -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. +The `Dockerfile` is expected to be found in a specific directory, depending on the deploy approach: -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. +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `dockerfile-path` property: ```shell -dokku builder-dockerfile:set node-js-app dockerfile-path Dockerfile2 +dokku builder-dockerfile:set node-js-app dockerfile-path .dokku/Dockerfile ``` +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, the build will fail. + The default value may be set by passing an empty value for the option: ```shell diff --git a/docs/deployment/builders/lambda.md b/docs/deployment/builders/lambda.md index 9df4501c6..48e8a27bd 100644 --- a/docs/deployment/builders/lambda.md +++ b/docs/deployment/builders/lambda.md @@ -42,14 +42,19 @@ The `lambda` builder plugin delegates all build logic to [lambda-builder](https: ### Changing the `lambda.yml` location -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. +The `lambda.yml` is expected to be found in a specific directory, depending on the deploy approach: -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. +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `lambdayml-path` property: ```shell dokku builder-lambda:set node-js-app lambdayml-path .dokku/lambda.yml ``` +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, the build will fail. + The default value may be set by passing an empty value for the option: ```shell diff --git a/docs/deployment/builders/nixpacks.md b/docs/deployment/builders/nixpacks.md index 77882bfb0..46559ca68 100644 --- a/docs/deployment/builders/nixpacks.md +++ b/docs/deployment/builders/nixpacks.md @@ -47,12 +47,19 @@ dokku docker-options:add node-js-app build '--env NODE_ENV=production' ### Changing the `nixpacks.toml` location -When deploying a monorepo, it may be desirable to specify the specific path of the `nixpacks.toml` file to use for a given app. This can be done via the `builder-nixpacks:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail. +The `nixpacks.toml` is expected to be found in a specific directory, depending on the deploy approach: + +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `nixpackstoml-path` property: ```shell -dokku builder-nixpacks:set node-js-app nixpackstoml-path nixpacks2.toml +dokku builder-nixpacks:set node-js-app nixpackstoml-path .dokku/nixpacks.toml ``` +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, the build will fail. + The default value may be set by passing an empty value for the option: ```shell diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md index 78379c387..2dd3c90a2 100644 --- a/docs/networking/proxies/nginx.md +++ b/docs/networking/proxies/nginx.md @@ -177,26 +177,36 @@ Alternatively, you may push an app to your Dokku host with a name like "00-defau > [!IMPORTANT] > New as of 0.5.0 -Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. This may be overridden by committing the [default configuration template](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil) to a file named `nginx.conf.sigil` in the root of the app repository. +Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. This may be overridden by committing the [default configuration template](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil) to a file named `nginx.conf.sigil`. -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`. +The `nginx.conf.sigil` is expected to be found in a specific directory, depending on the deploy approach: -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. +- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands. +- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`). + +Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `nginx-conf-sigil-path` property: ```shell 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. +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `nginx.conf.sigil`. -```shell -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. +The default value may be set by passing an empty value for the option: ```shell dokku nginx:set node-js-app nginx-conf-sigil-path +``` + +The `nginx-conf-sigil-path` property can also be set globally. The global default is `nginx.conf.sigil`, and the global value is used when no app-specific value is set. + +```shell +dokku nginx:set --global nginx-conf-sigil-path nginx.conf.sigil +``` + +The default value may be set by passing an empty value for the option. + +```shell dokku nginx:set --global nginx-conf-sigil-path ``` diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 747cb5b84..abc64ebac 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -164,9 +164,9 @@ Sometimes it may be desirable to set a different path for a given app, e.g. when dokku ps:set node-js-app procfile-path .dokku/Procfile ``` -The value is the path to the desired file *relative* to the base search directory (absolute paths don't work by design). If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `Procfile`. +The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `Procfile`. -If a value is set, the default value may be set back by passing an empty value for the property: +The default value may be set by passing an empty value for the option: ```shell dokku ps:set node-js-app procfile-path