From 5dd78e2b869f0fe893310a2f97cb65fe970b106b Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 19 Aug 2023 13:29:12 -0400 Subject: [PATCH 1/5] docs: update markdownlint rules for better formatting --- .github/linters/.markdown-lint.yml | 27 ++++++ .github/workflows/lint.yml | 14 ++-- .gitignore | 1 + CONTRIBUTING.md | 32 ++++---- HISTORY.md | 82 +++++++++---------- ISSUE_TEMPLATE.md | 10 +-- docs.mk | 2 +- docs/advanced-usage/deployment-tasks.md | 1 - docs/advanced-usage/docker-options.md | 2 +- docs/advanced-usage/event-logs.md | 2 +- docs/advanced-usage/persistent-storage.md | 7 +- docs/appendices/0.10.0-migration-guide.md | 4 +- docs/appendices/0.21.0-migration-guide.md | 2 +- docs/appendices/0.25.0-migration-guide.md | 2 +- docs/appendices/0.26.0-migration-guide.md | 2 +- docs/appendices/0.27.0-migration-guide.md | 1 + docs/appendices/0.5.0-migration-guide.md | 22 ++--- docs/appendices/0.6.0-migration-guide.md | 36 ++++---- docs/appendices/0.8.0-migration-guide.md | 4 +- docs/community/plugins.md | 2 +- docs/configuration/environment-variables.md | 7 +- docs/deployment/application-deployment.md | 4 +- .../deployment/builders/builder-management.md | 12 +-- .../builders/cloud-native-buildpacks.md | 18 ++-- .../builders/herokuish-buildpacks.md | 8 +- docs/deployment/methods/git.md | 2 +- docs/deployment/remote-commands.md | 4 +- docs/deployment/schedulers/docker-local.md | 11 ++- .../schedulers/scheduler-management.md | 18 ++-- docs/deployment/user-management.md | 2 - docs/deployment/zero-downtime-deploys.md | 4 +- docs/development/plugin-triggers.md | 5 +- docs/enterprise/pro.md | 2 +- docs/getting-started/advanced-installation.md | 2 +- docs/getting-started/install/vagrant.md | 2 +- docs/getting-started/installation/index.md | 16 ++-- docs/getting-started/troubleshooting.md | 18 ++-- docs/networking/port-management.md | 3 +- docs/networking/proxies/nginx.md | 3 +- docs/networking/proxy-management.md | 30 +++---- docs/processes/process-management.md | 10 +-- docs/processes/scheduled-cron-tasks.md | 5 +- tests/apps/multi/README.md | 2 +- tests/apps/scala/README.md | 15 ++-- 44 files changed, 243 insertions(+), 215 deletions(-) diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml index 2b7650bb2..e16596c0a 100644 --- a/.github/linters/.markdown-lint.yml +++ b/.github/linters/.markdown-lint.yml @@ -8,3 +8,30 @@ MD013: false # Inline HTML # https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033 MD033: false + +# List indentation +# 2 spaces breaks list formatting in mkdocs +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md007 +MD007: + indent: 4 + +# Fenced code blocks should have a language specified +# We use a second, un-languaged code block to denote the output +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md040 +MD040: false + +# Blank line inside blockquote +# This is typically done when a section has a "New as of" or "Warning" in addition to a note +# May wish to take advantage of github-style admonitions +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md028 +MD028: false + +# No duplicate headers +# HISTORY.md has a ton of these +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024 +MD024: false + +# First line h1 +# The issue template doesn't have one +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041 +MD041: false diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index d81d19a8e..c9197c8d3 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -27,12 +27,16 @@ jobs: steps: - name: Clone uses: actions/checkout@v3 - - name: Run markdown-lint - uses: avto-dev/markdown-lint@04d43ee9191307b50935a753da3b775ab695eceb - # v1.5.0 => 04d43ee9191307b50935a753da3b775ab695eceb + - name: Setup node + uses: actions/setup-node@v3 with: - config: '.github/linters/.markdown-lint.yml' - args: './README.md' + node-version: '20' + cache: 'npm' + cache-dependency-path: '.github/workflows/lint.yml' + - name: Install markdownlint-cli + run: npm install -g markdownlint-cli@0.35.0 + - name: Run markdown-lint + run: markdownlint -c .github/linters/.markdown-lint.yml *.md **/*.md packer: name: packer diff --git a/.gitignore b/.gitignore index deb157886..59cad9aa4 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ test-results/ stack.tgz tmp coverage.out +site diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6dd86788..4b5e36719 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,11 +19,11 @@ a chance of keeping on top of things. - [Reporting Security Issues](#reporting-security-issues) - [Reporting Issues](#reporting-other-issues) - [Contributing](#contributing) - - [Making Changes](#making-changes) - - [Which branch to base the work](#which-branch-to-base-the-work) - - [Submitting Changes](#submitting-changes) - - [When will my change be merged?](#when-will-my-change-be-merged) - - [Running tests locally](#running-tests-locally) + - [Making Changes](#making-changes) + - [Which branch to base the work](#which-branch-to-base-the-work) + - [Submitting Changes](#submitting-changes) + - [When will my change be merged?](#when-will-my-change-be-merged) + - [Running tests locally](#running-tests-locally) - [Additional Resources](#additional-resources) ## Reporting security issues @@ -65,24 +65,24 @@ need to do - Make sure you have a [GitHub account](https://github.com/signup/free). - Submit an [issue](https://github.com/dokku/dokku/issues), assuming one does not already exist. - - Clearly describe the issue including steps to reproduce when it is a bug. - - Make sure you fill in the earliest version that you know has the issue. + - Clearly describe the issue including steps to reproduce when it is a bug. + - Make sure you fill in the earliest version that you know has the issue. - Fork the repository on GitHub. ### Making Changes - Create a topic branch from where you want to base your work. - - This is usually the master branch. - - Only target an existing branch if you are certain your fix must be on that - branch. - - To quickly create a topic branch based on master; `git checkout -b my_contribution origin/master`. - It is best to avoid working directly on the `master` branch. Doing so will + - This is usually the master branch. + - Only target an existing branch if you are certain your fix must be on that + branch. + - To quickly create a topic branch based on master; `git checkout -b my_contribution origin/master`. + It is best to avoid working directly on the `master` branch. Doing so will help avoid conflicts if you pull in updates from origin. - Make commits of logical units. Implementing a new function and calling it in another file constitute a single logical unit of work. - - Before you make a pull request, squash your commits into logical units of work - using `git rebase -i` and `git push -f`. - - A majority of submissions should have a single commit, so if in doubt, + - Before you make a pull request, squash your commits into logical units of work + using `git rebase -i` and `git push -f`. + - A majority of submissions should have a single commit, so if in doubt, squash your commits down to one commit. - Check for unnecessary whitespace with `git diff --check` before committing. - Use descriptive commit messages and reference the #issue number. @@ -92,7 +92,7 @@ need to do - Your work should apply the [Dokku coding standards](https://github.com/progrium/bashstyle) - Pull requests must be cleanly rebased on top of master without multiple branches mixed into the PR. - - **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your + - **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your feature branch to update your pull request rather than `merge master`. ### Which branch to base the work diff --git a/HISTORY.md b/HISTORY.md index 03e19e4b2..1cb8993a2 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -374,7 +374,7 @@ sudo DOKKU_TAG=v0.30.4 bash bootstrap.sh ### Bug Fixes -- #5786: @obrienmd Detect id_ed25519.pub in git:public-key command +- #5786: @obrienmd Detect id_ed25519.pub in git:public-key command - #5758: @josegonzalez Support pack-based images that do not have a Procfile ### New Features @@ -999,7 +999,7 @@ See the [0.28.0 migration guide](/docs/appendices/0.28.0-migration-guide.md) for ### New Features -- #5300: @josegonzalez Add the ability to disable the init process +- #5300: @josegonzalez Add the ability to disable the init process - #5295: @josegonzalez Add an official caddy proxy implementation - #5293: @josegonzalez Add an official traefik proxy implementation - #5202: @josegonzalez Add builder-lambda plugin @@ -1063,7 +1063,7 @@ sudo DOKKU_TAG=v0.27.9 bash bootstrap.sh ### Other -- #5184: @yasoob New website. Closes #5175 +- #5184: @yasoob New website. Closes #5175 - #5270: @dependabot[bot] chore(deps): bump werkzeug from 2.2.0 to 2.2.1 in /tests/apps/python-flask - #5265: @dependabot[bot] chore(deps): bump werkzeug from 2.1.2 to 2.2.0 in /tests/apps/python-flask - #5264: @dependabot[bot] chore(deps): bump sinatra from 2.2.1 to 2.2.2 in /tests/apps/ruby @@ -2736,7 +2736,7 @@ See the [0.22.0 migration guide](/docs/appendices/0.22.0-migration-guide.md) for - #4160: @nerg4l Rewrite logs plugin in Go - #4149: @josegonzalez Rewrite ps plugin in golang -- #4080: @hugopeixoto Stop using VHOST when listing app domains and urls +- #4080: @hugopeixoto Stop using VHOST when listing app domains and urls - #4117: @josegonzalez Rewrite app-json plugin in golang - #4113: @josegonzalez Drop herokuish release code @@ -3379,7 +3379,7 @@ sudo DOKKU_TAG=v0.19.1 bash bootstrap.sh ### Bug Fixes -- #3713: @josegonzalez Require nginx 1.13+ in order to enable tls1.3 +- #3713: @josegonzalez Require nginx 1.13+ in order to enable tls1.3 ## 0.19.0 @@ -4745,7 +4745,7 @@ sudo DOKKU_TAG=v0.13.1 bash bootstrap.sh - #2683: @josegonzalez Ensure we have an example for adding keys as another user - #2682: @josegonzalez Clarify supported stanzas in app.json - #2679: @callahad Remove unnecessary Linode-specific instructions -- #2670: @znz Remove duplicated `(i.e. ` +- #2670: @znz Remove duplicated `(i.e.` ### Documentation @@ -5099,7 +5099,7 @@ Thanks to all the contributors who helped with this release, and a special thank ## 0.5.8 -This release is the last release in the `0.5.x` series, and as such is mainly a bugfix release. Users are highly encouraged to upgrade to this release *before* moving to the upcoming `0.6.x` release, as we will be removing deprecated features at that point. +This release is the last release in the `0.5.x` series, and as such is mainly a bugfix release. Users are highly encouraged to upgrade to this release _before_ moving to the upcoming `0.6.x` release, as we will be removing deprecated features at that point. Thanks to all the contributors who helped with this release! @@ -5291,7 +5291,7 @@ That was quick! This is a bugfix release to fix issues in the packaging and rele This is our largest, most feature-packed release in the history of the dokku project. Lots of delicious things, including: -- Support for docker 1.10/1.11. You *must* have docker 1.9.1+ to install dokku. +- Support for docker 1.10/1.11. You _must_ have docker 1.9.1+ to install dokku. - Revamped documentation website - [Deployment Tasks](https://dokku.com/docs/advanced-usage/deployment-tasks/) - Heroku-style management of [dockerfile processes](https://dokku.com/docs/deployment/builders/dockerfiles/#procfiles-and-multiple-processes) @@ -5390,7 +5390,7 @@ Thanks to all the contributors who helped with this release! ## 0.4.13 -We lied. *This* is the final 0.4.x release. This specific release fixes support for bash `4.2`, which may be the only bash version available for certain testing environments. +We lied. _This_ is the final 0.4.x release. This specific release fixes support for bash `4.2`, which may be the only bash version available for certain testing environments. Thanks to all the contributors who helped with this release! @@ -5444,7 +5444,7 @@ Thanks to all the contributors who helped with this release! This release is mostly a bugfix release, though we have a few important changes: - `dokku plugin:update` can now be used to update a specific plugin. Previously, this could potentially result in an error a user would have to manually resolve. -- We have started labeling all dokku-managed containers. In a future minor release, triggering a `dokku cleanup` will remove *only* exited containers that are managed by dokku. This change allows users to start containers outside of dokku and be assured that dokku would not inadvertently remove them. +- We have started labeling all dokku-managed containers. In a future minor release, triggering a `dokku cleanup` will remove _only_ exited containers that are managed by dokku. This change allows users to start containers outside of dokku and be assured that dokku would not inadvertently remove them. Thanks to all the contributors who helped with this release! @@ -5790,11 +5790,11 @@ One new feature is colorized logging output, which should make it easier to debu This is our first minor release in almost a year. Many new features and removals have occurred, so here is a neat summary: - Plugins are now triggered via `plugn`. Notably, you'll need add a `plugin.toml` to describe the plugin as well as use `plugn trigger` instead of `pluginhook` to trigger plugin callbacks. Please see the [plugin creation documentation](https://dokku.com/docs/development/plugin-creation/) for more details. -- A few new official plugins have been added to the core, including [image tagging](https://dokku.com/docs/deployment/application-deployment/), [certificate management](https://dokku.com/docs/configuration/ssl/), a tar-based deploy solution, and much more. Check out the *New Features* section for more details. +- A few new official plugins have been added to the core, including [image tagging](https://dokku.com/docs/deployment/application-deployment/), [certificate management](https://dokku.com/docs/configuration/ssl/), a tar-based deploy solution, and much more. Check out the _New Features_ section for more details. - We've removed a few deprecated plugin callbacks. Please see the [plugin triggers documentation](https://dokku.com/docs/development/plugin-triggers/) to see what is available. - [Official datastorage plugins](https://github.com/dokku) have been created for the most commonly used datastores. If you previously used/maintained a community contributed plugin, please check these out. We'll be adding more official plugins as time goes on. -Thanks to the *many* contributors for making this release our best release so far, and special thanks to both @michaelshobbs and @Flink for pushing along the `0.4.0` release! +Thanks to the _many_ contributors for making this release our best release so far, and special thanks to both @michaelshobbs and @Flink for pushing along the `0.4.0` release! ### Deprecations and Removals @@ -6116,10 +6116,10 @@ This release pegs Dokku to Docker 1.6.2. Docker 1.7.0 introduced changes in `doc - #1028: @Flink [docs] Add rails-logs to plugins - #1031: @michaelshobbs Upgrade docker in CI to 1.5.0 - #1029: @assaf Added several enhancements for CHECKS file: - - Specify how long to wait before running first check - - Specify timeout for each check - - Check specific hosts, e.g. http://signin.example.com - - Check both HTTP and HTTPS resources + - Specify how long to wait before running first check + - Specify timeout for each check + - Check specific hosts, e.g. [http://signin.example.com](http://signin.example.com) + - Check both HTTP and HTTPS resources - #1032: @cameron-martin Updated dokku-installer to use relative path - #1035: @Flink [docs] Add dokku-http-auth to plugins - #1040: @ebeigarts [docs] Add dokku-slack plugin information @@ -6223,12 +6223,12 @@ This release pegs Dokku to Docker 1.6.2. Docker 1.7.0 introduced changes in `doc ## 0.3.9 - #787: @josegonzalez/@michaelshobbs Official user-env-compile plugin - - Uses ENV and APP/ENV files - - Supports old `BUILD_ENV` files (which are likely in wide-use) - - Allows user's to override globals with app-specific configuration - - Migrate `$DOKKU_ROOT/BUILD_ENV` to `$DOKKU_ROOT/ENV` if the former exists and the latter does not - - Drop `BUILD_ENV` support in favor of just `ENV` via a `mv` command - - Add default ENV with `CURL_TIMEOUT` and `CURL_CONNECT_TIMEOUT` + - Uses ENV and APP/ENV files + - Supports old `BUILD_ENV` files (which are likely in wide-use) + - Allows user's to override globals with app-specific configuration + - Migrate `$DOKKU_ROOT/BUILD_ENV` to `$DOKKU_ROOT/ENV` if the former exists and the latter does not + - Drop `BUILD_ENV` support in favor of just `ENV` via a `mv` command + - Add default ENV with `CURL_TIMEOUT` and `CURL_CONNECT_TIMEOUT` - #811: @abossard Increased `server_names_hash_bucket_size` in nginx.conf to 512 - #814: @josegonzalez Source files in $DOKKU_ROOT/.dokkurc directory and add `dokku trace` command - #816: @josegonzalez Add documentation for user-env feature @@ -6337,25 +6337,25 @@ This release pegs Dokku to Docker 1.6.2. Docker 1.7.0 introduced changes in `doc ## 0.2.0 (2013-11-24) -* Added DOKKU_TRACE variable for verbose trace information -* Added an installer (for pre-built images) -* Application config (environment variable management) -* Backup/import plugin -* Basic hooks/plugin system -* Cache dir is preserved across builds -* Command to delete an application -* Exposed commands over SSH using sshcommand -* Git handling is moved to a plugin -* Integration test coverage -* Pulled nginx vhosts out into plugin -* Run command -* Separated dokku and buildstep more cleanly -* Uses latest version of Docker again +- Added DOKKU_TRACE variable for verbose trace information +- Added an installer (for pre-built images) +- Application config (environment variable management) +- Backup/import plugin +- Basic hooks/plugin system +- Cache dir is preserved across builds +- Command to delete an application +- Exposed commands over SSH using sshcommand +- Git handling is moved to a plugin +- Integration test coverage +- Pulled nginx vhosts out into plugin +- Run command +- Separated dokku and buildstep more cleanly +- Uses latest version of Docker again ## 0.1.0 (2013-06-15) - * First release - * Bootstrap script for Ubuntu system - * Basic push / deploy with git - * Hostname support with Nginx - * Support for Java, Ruby, Node.js buildpacks +- First release + - Bootstrap script for Ubuntu system + - Basic push / deploy with git + - Hostname support with Nginx + - Support for Java, Ruby, Node.js buildpacks diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index 9dff003bd..73adb6ecf 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -39,10 +39,10 @@ - The nginx configuration (if applicable) via `dokku nginx:show-config APP_NAME` - Link to the exact repository being deployed (if possible/applicable): - If a deploy is failing or behaving unexpectedly: - - Application name - - The type of application being deployed (node, php, python, ruby, etc.) - - If using buildpacks, which custom buildpacks are in use - - If using a `Dockerfile`, the contents of that file - - If it exists, the contents of your `Procfile`. + - Application name + - The type of application being deployed (node, php, python, ruby, etc.) + - If using buildpacks, which custom buildpacks are in use + - If using a `Dockerfile`, the contents of that file + - If it exists, the contents of your `Procfile`. - Output of failing Dokku commands after running `dokku trace:on` (BEWARE: `trace:on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXX): diff --git a/docs.mk b/docs.mk index 911eef17d..f9c1f4717 100644 --- a/docs.mk +++ b/docs.mk @@ -1,6 +1,6 @@ .PHONY: docs-build-image docs-build-image: - docker build -f docs/_build/Dockerfile --progress plain -t app/mkdocs . + docker build -f docs/_build/Dockerfile --progress plain -t app/mkdocs . .PHONY: docs-build docs-build: diff --git a/docs/advanced-usage/deployment-tasks.md b/docs/advanced-usage/deployment-tasks.md index f13550445..c93b7c456 100644 --- a/docs/advanced-usage/deployment-tasks.md +++ b/docs/advanced-usage/deployment-tasks.md @@ -59,7 +59,6 @@ When deploying a monorepo, it may be desirable to specify the specific path of t 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 .dokku/app.json ``` diff --git a/docs/advanced-usage/docker-options.md b/docs/advanced-usage/docker-options.md index 16e82cd3e..153e499cd 100644 --- a/docs/advanced-usage/docker-options.md +++ b/docs/advanced-usage/docker-options.md @@ -27,7 +27,7 @@ Dokku deploys your application in multiple "phases" and the `docker-options` plu Manipulation of docker options will not restart running containers. This enables multiple options to be set/unset before final application. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` in order to take effect. -More information on supported Docker options can be found here: https://docs.docker.com/engine/reference/commandline/run/. +More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/). Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container. diff --git a/docs/advanced-usage/event-logs.md b/docs/advanced-usage/event-logs.md index 1338fd869..fc05b869a 100644 --- a/docs/advanced-usage/event-logs.md +++ b/docs/advanced-usage/event-logs.md @@ -75,4 +75,4 @@ pre-release-buildpack pre-release-dockerfile receive-app update -``` \ No newline at end of file +``` diff --git a/docs/advanced-usage/persistent-storage.md b/docs/advanced-usage/persistent-storage.md index 4ebf2b185..580764bfa 100644 --- a/docs/advanced-usage/persistent-storage.md +++ b/docs/advanced-usage/persistent-storage.md @@ -36,7 +36,6 @@ dokku storage:list node-js-app The output format can also be set to `json` for programmatic access: - ```shell dokku storage:list node-js-app --format json ``` @@ -70,11 +69,11 @@ dokku storage:ensure-directory node-js-app By default, permissions are set for usage with Herokuish buildpacks. These permissions can be changed via the `--chown` option according to the following table: - `--chown herokuish` (default): Use `32767:32767` as the folder permissions. - - This is used for apps deployed with Buildpacks via Herokuish. + - This is used for apps deployed with Buildpacks via Herokuish. - `--chown heroku`: Use `1000:1000` as the folder permissions. - - This is used for apps deployed with Cloud Native Buildpacks using the `heroku/buildpacks` builder. + - This is used for apps deployed with Cloud Native Buildpacks using the `heroku/buildpacks` builder. - `--chown packeto`: Use `2000:2000` as the folder permissions. - - This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `packeto` builders. + - This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `packeto` builders. - `--chown false`: Skips the `chown` call. Users deploying via Dockerfile will want to specify `--chown false` and manually `chown` the created directory if the user and/or group id of the runnning process in the deployed container do not correspond to any of the above options. diff --git a/docs/appendices/0.10.0-migration-guide.md b/docs/appendices/0.10.0-migration-guide.md index 053155738..ec3aa3733 100644 --- a/docs/appendices/0.10.0-migration-guide.md +++ b/docs/appendices/0.10.0-migration-guide.md @@ -4,10 +4,10 @@ By default, Dokku will ship a PCI Compliant nginx configuration. For developers whose users are on older browsers or mobile devices, you may need to ship a custom `nginx.conf.sigil` to enable ciphers for older browsers. -See the [nginx customization](/docs/networking/proxies/nginx/#customizing-the-nginx-configuration) docs for more details. +See the [nginx customization](/docs/networking/proxies/nginx.md#customizing-the-nginx-configuration) docs for more details. ## Nginx Error Pages We now ship with nicer error pages by default. You are free to customize your Dokku installation via a custom `nginx.conf.sigil` to change what error pages are displayed in different circumstances. -See the [nginx customization](/docs/networking/proxies/nginx/#customizing-the-nginx-configuration) docs for more details. +See the [nginx customization](/docs/networking/proxies/nginx.md#customizing-the-nginx-configuration) docs for more details. diff --git a/docs/appendices/0.21.0-migration-guide.md b/docs/appendices/0.21.0-migration-guide.md index 2f16cdb6e..a2131da6a 100644 --- a/docs/appendices/0.21.0-migration-guide.md +++ b/docs/appendices/0.21.0-migration-guide.md @@ -8,7 +8,7 @@ The `tls` name is no longer a reserved app name, and can be used by applications - `git#git_deploy_branch()` is deprecated in favor of `plugn trigger git-deploy-branch`. - The `config` command is deprecated in favor of `config:show`. - - Usage of this command in conjunction with either the `--export` or `--shell` flag is deprecated in favor of `config:export --format` with the correct format value (`exports` or `shell`, respectively). + - Usage of this command in conjunction with either the `--export` or `--shell` flag is deprecated in favor of `config:export --format` with the correct format value (`exports` or `shell`, respectively). - The `nginx:build-config` command is deprecated in favor of `proxy:build-config`. ## Removals diff --git a/docs/appendices/0.25.0-migration-guide.md b/docs/appendices/0.25.0-migration-guide.md index 1ff9ab5b8..c6ebb6609 100644 --- a/docs/appendices/0.25.0-migration-guide.md +++ b/docs/appendices/0.25.0-migration-guide.md @@ -19,7 +19,7 @@ Before upgrading, uninstall the registry plugin via `dokku plugin:uninstall regi - 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. - The `pre-deploy` plugin trigger is now called internally by Dokku. Scheduler plugins should avoid calling this trigger, as any image changes introduced by subsequent trigger calls will be ignored. - The default image used for Herokuish Buildpack builds is now `gliderlabs/herokuish:latest-20`, and is based on both the `heroku-20` stack as well as Ubuntu 20.04. Users that wish to stick with the old, `heroku-18`/Ubuntu 18.04 builder may specify `gliderlabs/herokuish:latest-18` as their builder image. Please see the [herokuish buildpack deployment documentation](/docs/deployment/builders/herokuish-buildpacks.md#customizing-the-buildpack-stack-builder) for more information on how to specify a custom buildpack stack builder. - - This change does not impact any users of Cloud Native Buildpacks. + - This change does not impact any users of Cloud Native Buildpacks. - We fixed an issue that required extracting Procfiles at the beginning of a deploy. Due to this change, a `Dockerfile` app contains a `Procfile` that does not specify a `web` process will fail to start. Usage of a `Procfile` with _only_ a `release` command should be replaced with a `scripts.dokku.postdeploy` deployment task in the `app.json` file. The alternative is to define the `web` process in the `Procfile`. See the [deployment task documentation](/docs/advanced-usage/deployment-tasks.md) for more information. ### Deprecations diff --git a/docs/appendices/0.26.0-migration-guide.md b/docs/appendices/0.26.0-migration-guide.md index b752e8cc2..dbb3af106 100644 --- a/docs/appendices/0.26.0-migration-guide.md +++ b/docs/appendices/0.26.0-migration-guide.md @@ -9,4 +9,4 @@ - The `scheduler` plugin now controls the scheduler in use for deploys. Apps will have their `DOKKU_SCHEDULER` environment variables migrated to the scheduler plugin, after which that value will be removed from said app. Please see the [scheduler documentation](/docs/deployment/schedulers/scheduler-management.md) for more information. - The `deploy-source` metadata from `apps:report` is now no longer computed on the fly, but hydrated at deploy time via the `deploy-source-set` trigger. This value may be empty until your next deploy. - - Additionally, the `deploy-source` trigger has now been removed. + - Additionally, the `deploy-source` trigger has now been removed. diff --git a/docs/appendices/0.27.0-migration-guide.md b/docs/appendices/0.27.0-migration-guide.md index 0f161bdf1..1519f4b5b 100644 --- a/docs/appendices/0.27.0-migration-guide.md +++ b/docs/appendices/0.27.0-migration-guide.md @@ -3,6 +3,7 @@ ## Changes - Renaming an application will now only rename domains that are associated with global domains. As an example: + ```shell dokku domains:set-global dokku.me dokku apps:create node-js-app diff --git a/docs/appendices/0.5.0-migration-guide.md b/docs/appendices/0.5.0-migration-guide.md index 86dfb0d11..fe0f1fd6b 100644 --- a/docs/appendices/0.5.0-migration-guide.md +++ b/docs/appendices/0.5.0-migration-guide.md @@ -3,23 +3,23 @@ ## `nginx-vhosts` plugin - The nginx-vhosts template language is now [sigil](https://github.com/gliderlabs/sigil) - - No need to escape literal `$` characters (or other "bash-isms") - - Template variables are represented as {{ .VARIABLE_NAME }} - - A detailed list of template variables can be found [here](/docs/networking/proxies/nginx.md#available-template-variables) + - No need to escape literal `$` characters (or other "bash-isms") + - Template variables are represented as {{ .VARIABLE_NAME }} + - A detailed list of template variables can be found [here](/docs/networking/proxies/nginx.md#available-template-variables) - A custom nginx-vhosts template must be named `nginx.conf.sigil` - - The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app) - - Dokku no longer looks for this file in `/home/dokku/node-js-app` on the Dokku server - - Check out an example template [here](/docs/networking/proxies/nginx.md) + - The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app) + - Dokku no longer looks for this file in `/home/dokku/node-js-app` on the Dokku server + - Check out an example template [here](/docs/networking/proxies/nginx.md) - Support for server-wide SSL certs have been dropped in favor of using the `certs` plugin - - `dokku certs:add node-js-app < certs.tar` + - `dokku certs:add node-js-app < certs.tar` - All domains for an SSL-enabled app will be redirected to https by default - - This can be overridden with a custom template + - This can be overridden with a custom template - Replaced "magic" `NO_VHOST` variable with `domains:enable/disable` - Simplified zero downtime control - - `checks:enable/disable` + - `checks:enable/disable` ## Dockerfile apps with exposed ports - Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/docs/deployment/builders/dockerfiles.md#exposed-ports) - - Note that nginx will proxy the same port numbers to listen publicly - - UDP ports can be exposed by disabling the [nginx proxy](/docs/networking/proxy-management.md) with `dokku proxy:disable node-js-app` + - Note that nginx will proxy the same port numbers to listen publicly + - UDP ports can be exposed by disabling the [nginx proxy](/docs/networking/proxy-management.md) with `dokku proxy:disable node-js-app` diff --git a/docs/appendices/0.6.0-migration-guide.md b/docs/appendices/0.6.0-migration-guide.md index 23fd4e767..fe9cd7247 100644 --- a/docs/appendices/0.6.0-migration-guide.md +++ b/docs/appendices/0.6.0-migration-guide.md @@ -3,30 +3,30 @@ ## Zero-downtime deployment - You can now **actually** disable zero-downtime deployments per-app and per-process-type - - Some config variables have been moved around - - `DOKKU_CHECKS_ENABLED` has been migrated to `DOKKU_CHECKS_SKIPPED` - - `DOKKU_CHECKS_DISABLED` is now a thing - - The values for the above can be a comma-separated list of process-types or the literal string `_all_` - - See the [updated `checks`](/docs/deployment/zero-downtime-deploys.md) docs for more info + - Some config variables have been moved around + - `DOKKU_CHECKS_ENABLED` has been migrated to `DOKKU_CHECKS_SKIPPED` + - `DOKKU_CHECKS_DISABLED` is now a thing + - The values for the above can be a comma-separated list of process-types or the literal string `_all_` + - See the [updated `checks`](/docs/deployment/zero-downtime-deploys.md) docs for more info ## Proxy port mapping - You can now configure host -> container proxy port mappings - - The UI is handled by the [proxy](/docs/networking/proxy-management.md) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes. + - The UI is handled by the [proxy](/docs/networking/proxy-management.md) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes. - Default port mappings - - buildpack apps will be set to `http:80:5000` and will also include `https:443:5000` if SSL is enabled. - - dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container. - - You may override this behavior with the [`proxy:ports-*` commands](/docs/networking/proxy-management.md) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command - - dockerfile apps without explicitly exposed ports will behave the same as a buildpack app - - NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands + - buildpack apps will be set to `http:80:5000` and will also include `https:443:5000` if SSL is enabled. + - dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container. + - You may override this behavior with the [`proxy:ports-*` commands](/docs/networking/proxy-management.md) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command + - dockerfile apps without explicitly exposed ports will behave the same as a buildpack app + - NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands ## Calling the `dokku` binary - Plugins should *not* call the `dokku` binary directly. Clients using the `--app` argument are potentially broken, amongst others, when doing so. Instead, please source the `functions` file for a given plugin when attempting to call Dokku internal functions. As a result, the following Dokku commands are no longer publicly exposed: - - `dokku build` - - `dokku receive` - - `dokku release` - - `dokku tar:build` - - `dokku tar:build-locked` - - `dokku git:build` - - `dokku git:build-locked` + - `dokku build` + - `dokku receive` + - `dokku release` + - `dokku tar:build` + - `dokku tar:build-locked` + - `dokku git:build` + - `dokku git:build-locked` diff --git a/docs/appendices/0.8.0-migration-guide.md b/docs/appendices/0.8.0-migration-guide.md index 6247a3e51..f0881b0d1 100644 --- a/docs/appendices/0.8.0-migration-guide.md +++ b/docs/appendices/0.8.0-migration-guide.md @@ -2,13 +2,13 @@ ## Domain Management -You can now set global and app domains via `domains:set` and `domains:set-global`. See the [domains documentation](/docs/configuration/domains/) for more details. +You can now set global and app domains via `domains:set` and `domains:set-global`. See the [domains documentation](/docs/configuration/domains.md) for more details. ## Plugin Uninstallation A new `uninstall` plugin trigger was introduced. This functionality may be in use for newer plugins, so be aware that older Dokku versions may require manual cleanup. -See the [uninstall trigger documentation](/docs/development/plugin-triggers/#uninstall) for implementation instructions. +See the [uninstall trigger documentation](/docs/development/plugin-triggers.md#uninstall) for implementation instructions. ## Deployment Tasks diff --git a/docs/community/plugins.md b/docs/community/plugins.md index dc9d1d6b1..da144aeab 100644 --- a/docs/community/plugins.md +++ b/docs/community/plugins.md @@ -208,7 +208,7 @@ The following plugins have been removed as their functionality is now in Dokku C | [Volume (persistent storage)](https://github.com/ohardy/dokku-volume) | [ohardy][] | v0.5.0 (storage plugin) | 1 Conflicts with [VHOSTS Custom Configuration](https://github.com/neam/dokku-nginx-vhosts-custom-configuration) -2 Similar to the heroku-labs feature (see https://devcenter.heroku.com/articles/labs-user-env-compile) +2 Similar to the [heroku-labs feature](https://devcenter.heroku.com/articles/labs-user-env-compile) ### Unmaintained Plugins diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 464211d4a..cdcb804cd 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -14,6 +14,7 @@ config:keys (|--global) [--merged] config:set [--encoded] [--no-restart] (|--global) KEY1=VALUE1 [KEY2=VALUE2 ...] Set one or more config vars config:unset [--no-restart] (|--global) KEY1 [KEY2 ...] Unset one or more config vars ``` + > For security reasons - and as per [docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available _only_ during runtime, as noted in [this issue](https://github.com/dokku/dokku/issues/1860). Consider using [build arguments](/docs/deployment/builders/dockerfiles.md#build-time-configuration-variables) to expose variables during build-time for Dockerfile apps. Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys. @@ -28,7 +29,8 @@ You can set multiple environment variables at once: dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1 ``` -> Note: Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces: +Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces: + ```shell dokku config:set node-js-app KEY="VAL\ WITH\ SPACES" ``` @@ -58,8 +60,7 @@ dokku config:export node-js-app eval $(dokku config:export node-js-app) ``` -You can control the format of the exported variables with the `--format` flag. -`--format=shell` will output the variables in a single-line for usage in command-line utilities: +You can control the format of the exported variables with the `--format` flag. `--format=shell` will output the variables in a single-line for usage in command-line utilities: ```shell dokku config:export --format shell node-js-app diff --git a/docs/deployment/application-deployment.md b/docs/deployment/application-deployment.md index 67d54a48b..66522eb46 100644 --- a/docs/deployment/application-deployment.md +++ b/docs/deployment/application-deployment.md @@ -102,7 +102,7 @@ Once the deploy is complete, the application's web URL will be generated as abov Dokku supports deploying applications in a few ways: - [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) via [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks): See the [herokuish buildpacks documentation](/docs/deployment/builders/herokuish-buildpacks.md) to learn about the different ways to specify a buildpack. - - This is the default method used by Dokku. + - This is the default method used by Dokku. - [Dockerfile](https://docs.docker.com/reference/builder/): See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys. - [Docker Image](https://docs.docker.com/get-started/overview/#docker-objects): See the [docker image documentation](/docs/deployment/methods/git.md#initializing-an-app-repository-from-a-docker-image) to learn about how to deploy a Docker Image. @@ -148,7 +148,7 @@ dokku config:set ruby-getting-started DOKKU_SKIP_DEPLOY=true ### Redeploying or restarting -If you need to redeploy or restart your app: +If you need to redeploy or restart your app: ```shell # on the Dokku host diff --git a/docs/deployment/builders/builder-management.md b/docs/deployment/builders/builder-management.md index 4c383751b..d05df624d 100644 --- a/docs/deployment/builders/builder-management.md +++ b/docs/deployment/builders/builder-management.md @@ -131,14 +131,14 @@ dokku builder:report node-js-app --builder-selected To create a custom builder, the following triggers must be implemented: - `builder-build`: - - arguments: `BUILDER_TYPE` `APP` `SOURCECODE_WORK_DIR` - - description: Creates a docker image named with the output of `common#get_app_image_name $APP`. + - arguments: `BUILDER_TYPE` `APP` `SOURCECODE_WORK_DIR` + - description: Creates a docker image named with the output of `common#get_app_image_name $APP`. - `builder-detect`: - - arguments: `APP` `SOURCECODE_WORK_DIR` - - description: Outputs the name of the builder (without the `builder-` prefix) to use to build the app. + - arguments: `APP` `SOURCECODE_WORK_DIR` + - description: Outputs the name of the builder (without the `builder-` prefix) to use to build the app. - `builder-release`: - - arguments: `BUILDER_TYPE` `APP` `IMAGE_AG` - - description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately. + - arguments: `BUILDER_TYPE` `APP` `IMAGE_AG` + - description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately. Custom plugins names _must_ have the prefix `builder-` or builder overriding via `builder:set` may not function as expected. diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index 0e300ede4..718909a58 100644 --- a/docs/deployment/builders/cloud-native-buildpacks.md +++ b/docs/deployment/builders/cloud-native-buildpacks.md @@ -28,25 +28,27 @@ Builds will proceed with the `pack` cli for the app from then on. As this functionality is highly experimental, there are a number of caveats. Please note that not all issuesare listed below. - Specifying specific buildpacks is not currently possible. - - A future release will add support for specifying buildpacks via the `buildpacks` plugin. + - A future release will add support for specifying buildpacks via the `buildpacks` plugin. - There is currently no way to specify extra arguments for `pack` cli invocations. - - A future release will add support for injecting extra arguments during the build process. + - A future release will add support for injecting extra arguments during the build process. - The default process type is `web`. - Build cache is stored in Docker volumes instead of on disk. As such, `repo:purge-cache` currently has no effect. - - A future version will add integration with the `repo` plugin. + - A future version will add integration with the `repo` plugin. - `pack` is not currently included with Dokku, nor is it added as a package dependency. - - A future version will include it as a package dependency. + - A future version will include it as a package dependency. ### Detection This builder will be auto-detected in either the following cases: - The `DOKKU_CNB_EXPERIMENTAL` app environment variable is set to `1`. - ```shell - dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1 - ``` + + ```shell + dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1 + ``` + - A `project.toml` file exists in the root of the app repository. - - This file is consumed by `pack-cli` and used to describe how the app is built. + - This file is consumed by `pack-cli` and used to describe how the app is built. The builder can also be specified via the `builder:set` command: diff --git a/docs/deployment/builders/herokuish-buildpacks.md b/docs/deployment/builders/herokuish-buildpacks.md index 60b295f65..b9f07beb6 100644 --- a/docs/deployment/builders/herokuish-buildpacks.md +++ b/docs/deployment/builders/herokuish-buildpacks.md @@ -22,9 +22,9 @@ builder-herokuish:set () # Set or clear a builder-herokuish p Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following: - Set a `BUILDPACK_URL` environment variable - - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details. + - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details. - Create a `.buildpacks` file in the root of your repository. - - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands. + - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands. This page will cover usage of the `buildpacks` plugin. @@ -35,9 +35,9 @@ This page will cover usage of the `buildpacks` plugin. This builder will be auto-detected in either the following cases: - The `BUILDPACK_URL` app environment variable is set. - - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details. + - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details. - A `.buildpacks` file exists in the root of the app repository. - - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands. + - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands. The builder can also be specified via the `builder:set` command: diff --git a/docs/deployment/methods/git.md b/docs/deployment/methods/git.md index e69d17aaa..3088294f1 100644 --- a/docs/deployment/methods/git.md +++ b/docs/deployment/methods/git.md @@ -38,7 +38,7 @@ When an application is created via `git push`, Dokku will create the proper `pre dokku git:initialize node-js-app ``` -In order for the above command to succeed, the application _must_ already exist. +In order for the above command to succeed, the application _must_ already exist. > Warning: If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku. diff --git a/docs/deployment/remote-commands.md b/docs/deployment/remote-commands.md index 7d234e26d..beebfde22 100644 --- a/docs/deployment/remote-commands.md +++ b/docs/deployment/remote-commands.md @@ -91,7 +91,7 @@ In addition, the following commands have special local side-effects: #### Specifying a remote -While many users will only ever push to a single dokku remote from a given repository, it may be useful to point the same repository at multiple remotes, especially in the case of pre-production environments. This can be done via the `remote` commands. These commands are _only_ available within the official remote client, and are not server-side commands. +While many users will only ever push to a single dokku remote from a given repository, it may be useful to point the same repository at multiple remotes, especially in the case of pre-production environments. This can be done via the `remote` commands. These commands are *only* available within the official remote client, and are not server-side commands. To see your currently configured remote, run `dokku remote`. This will respect the `--remote` flag. @@ -101,7 +101,7 @@ To add a remote, run `dokku remote:add $REMOTE_NAME dokku@dokku.me:$APP_NAME`, r To remove a remote, run `dokku remote:remove $REMOTE_NAME`. This is equivalent to running `git remote remove $REMOTE_NAME`. -By default, the remote in use is `dokku`. To change the remote the client uses by default, run `dokku remote:set $REMOTE_NAME`, where `$REMOTE_NAME` is the name of your desired remote. This will not check the value specified, so that remote _must_ be available or errors will occur when running normal client commands. Note that specifying `--remote` when running dokku commands will override this configuration value. +By default, the remote in use is `dokku`. To change the remote the client uses by default, run `dokku remote:set $REMOTE_NAME`, where `$REMOTE_NAME` is the name of your desired remote. This will not check the value specified, so that remote *must* be available or errors will occur when running normal client commands. Note that specifying `--remote` when running dokku commands will override this configuration value. To clear the configured remote, run `dokku remote:unset`. The client will unset the configured remote, and will default back to `dokku`, or the value of `--remote` if specified. diff --git a/docs/deployment/schedulers/docker-local.md b/docs/deployment/schedulers/docker-local.md index 1d10bd7c3..5da54e1c5 100644 --- a/docs/deployment/schedulers/docker-local.md +++ b/docs/deployment/schedulers/docker-local.md @@ -121,7 +121,6 @@ This plugin implements various functionality through `plugn` triggers to integra - `ps:stop` - `run` - ### Logging support App logs for the `logs` command are fetched from running containers via the `docker` cli. To persist logs across deployments, consider using Dokku's [vector integration](/docs/deployment/logs.md#vector-logging-shipping) to ship logs to another service or a third-party platform. @@ -133,15 +132,15 @@ The `docker-local` scheduler supports a minimal list of resource _limits_ and _r #### Resource Limits - cpu: (docker option: `--cpus`), is specified in number of CPUs a process can access. - - See the ["CPU" section](https://docs.docker.com/config/containers/resource_constraints/#cpu) of the Docker Runtime Options documentation for more information. + - See the ["CPU" section](https://docs.docker.com/config/containers/resource_constraints/#cpu) of the Docker Runtime Options documentation for more information. - memory: (docker option: `--memory`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes). Default unit is `m` (megabytes). - - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information. + - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information. - memory-swap: (docker option: `--memory-swap`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes) - - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information. + - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information. - nvidia-gpus: (docker option: `--gpus`), is specified in number of Nvidia GPUs a process can access. - - See the ["GPU" section](https://docs.docker.com/config/containers/resource_constraints/#gpu) of the Docker Runtime Options documentation for more information. + - See the ["GPU" section](https://docs.docker.com/config/containers/resource_constraints/#gpu) of the Docker Runtime Options documentation for more information. #### Resource Reservations - memory: (docker option: `--memory-reservation`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes). Default unit is `m` (megabytes). - - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information. + - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information. diff --git a/docs/deployment/schedulers/scheduler-management.md b/docs/deployment/schedulers/scheduler-management.md index f41ca0390..04da2bc81 100644 --- a/docs/deployment/schedulers/scheduler-management.md +++ b/docs/deployment/schedulers/scheduler-management.md @@ -91,23 +91,23 @@ Custom plugins names _must_ have the prefix `scheduler-` or scheduler overriding At this time, the following dokku commands are used to implement a complete scheduler. - `apps:destroy`: stops the app processes on the scheduler - - triggers: post-delete, scheduler-register-retired, scheduler-retire + - triggers: post-delete, scheduler-register-retired, scheduler-retire - `apps:rename`: handles app renaming - - triggers: post-app-rename-setup + - triggers: post-app-rename-setup - `apps:clone`: handles app cloning - - triggers: post-app-clone-setup + - triggers: post-app-clone-setup - `deploy`: deploys app proceses and checks the status of a deploy - - triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed + - triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed - `enter`: enters a running container - - triggers: scheduler-enter + - triggers: scheduler-enter - `logs`: fetches app logs - - triggers: scheduler-logs + - triggers: scheduler-logs - `run`: starts one-off run containers (detached and non-detached) as well as listing run processes - - triggers: scheduler-run, scheduler-run-list + - triggers: scheduler-run, scheduler-run-list - `ps:stop`: stops app processes - - triggers: scheduler-stop + - triggers: scheduler-stop - `ps:inspect`: outputs inspect output for processes in an app - - triggers: scheduler-inspect + - triggers: scheduler-inspect Schedulers may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins. Additionally, a scheduler may implement other triggers in order handle any extra processes needed during a deploy. diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index e8e9fb214..8685bf56c 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -82,7 +82,6 @@ echo "$CONTENTS_OF_YOUR_PUBLIC_SSH_KEY_HERE" | dokku ssh-keys:add KEY_NAME SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc ``` - ```shell cat path/to/id_rsa.pub | dokku ssh-keys:add KEY_NAME ``` @@ -91,7 +90,6 @@ cat path/to/id_rsa.pub | dokku ssh-keys:add KEY_NAME SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc ``` - Admin users and root can add keys remotely by specifying the `dokku` bin on their `ssh` command: ```shell diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 57738dbaa..53ca0e444 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -163,12 +163,12 @@ A healthcheck entry takes the following properties: - `attempts`: (default: `3` seconds) Number of retry attempts to perform on failure. - `command`: (default `''` - empty string) Command to execute within container. - `content`: (default: `''` - empty string) Content to search in http path check output. -initialDelay default: 0, unit: seconds) Number of seconds to wait after a container has started before triggering the healthcheck. +- `initialDelay`: (default: 0, unit: seconds) Number of seconds to wait after a container has started before triggering the healthcheck. - `name`: (default: autogenerated) The name of the healthcheck. If unspecified, it will be autogenerated from the rest of the healthcheck information. - `path`: (default: `/` - for http checks): An http path to check. - `timeout`: (default: `5` seconds): Number of seconds to wait before timing out a healthcheck. - `type`: (default: `""` - none): Type of the healthcheck. Options: liveness, readiness, startup. -- `uptime`: (default: `""` - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries. +- `uptime`: (default: `""` - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries. - `wait`: (default: `5` seconds): Number of seconds to wait between healthcheck attempts. > Warning: Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported. diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index 1f75aef43..92e882b35 100644 --- a/docs/development/plugin-triggers.md +++ b/docs/development/plugin-triggers.md @@ -1161,7 +1161,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x - Description: Return the path to a `sigil` template that should be used to generate a given nginx configuration file. - Invoked by: `nginx-vhosts#build-config` - Arguments: `$APP $TEMPLATE_TYPE` - - The `TEMPLATE_TYPE` argument can be one of: `[app-config, hsts-config, validate-config]` + - The `TEMPLATE_TYPE` argument can be one of: `[app-config, hsts-config, validate-config]` - Example: ```shell @@ -1477,7 +1477,7 @@ APP="$1" ### `post-config-update` -- Description: Allows you to get notified when one or more configs is added or removed. Action can be `set` or `unset`. +- Description: Allows you to get notified when one or more configs is added or removed. Action can be `set` or `unset`. - Invoked by: `dokku config:set`, `dokku config:unset` - Arguments: `$APP` `set|unset` `key1=VALUE1 key2=VALUE2` - Example: @@ -2052,6 +2052,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x # TODO ``` + ### `ps-current-scale` - Description: Prints out the current scale contents (process-type=quantity) delimited by newlines. diff --git a/docs/enterprise/pro.md b/docs/enterprise/pro.md index bcf338c58..cbf42932b 100644 --- a/docs/enterprise/pro.md +++ b/docs/enterprise/pro.md @@ -29,4 +29,4 @@ Dokku Pro has the following functionality: - Authenticated HTTP(S) endpoints for git push functionality - Single Page App (SPA) Web UI exposing app, datastore, and ssh key management -While each release is fairly feature complete, individual features and documentation will expand over time. Feature development follows a monthly release cadence, with individual bug fixes released on an as needed basis. +While each release is fairly feature complete, individual features and documentation will expand over time. Feature development follows a monthly release cadence, with individual bug fixes released on an as needed basis. diff --git a/docs/getting-started/advanced-installation.md b/docs/getting-started/advanced-installation.md index 78a0e1969..1010fb910 100644 --- a/docs/getting-started/advanced-installation.md +++ b/docs/getting-started/advanced-installation.md @@ -78,7 +78,7 @@ Follow the [user management documentation](/docs/deployment/user-management.md) ## VMs with less than 1 GB of memory -Having less than 1 GB of system memory available for Dokku and its containers may result in unexpected errors, such as `! [remote rejected] master -> master (pre-receive hook declined)` during installation of NPM dependencies (https://github.com/npm/npm/issues/3867). +Having less than 1 GB of system memory available for Dokku and its containers may result in unexpected errors, such as `! [remote rejected] master -> master (pre-receive hook declined)` [during installation of NPM dependencies](https://github.com/npm/npm/issues/3867). To work around this issue, it might suffice to augment the Linux swap file size to a maximum of twice the physical memory size. diff --git a/docs/getting-started/install/vagrant.md b/docs/getting-started/install/vagrant.md index b3d48521f..4d6067725 100644 --- a/docs/getting-started/install/vagrant.md +++ b/docs/getting-started/install/vagrant.md @@ -36,7 +36,7 @@ Port 22 ``` - > For users that have customized the IP address of their VM - either in a custom `Vagrantfile` or via the `DOKKU_IP` environment variable - and are not using `10.0.0.2` for the Vagrant IP, you'll need to instead use the output of `vagrant ssh-config dokku` for your `~/.ssh/config` entry. + > For users that have customized the IP address of their VM - either in a custom `Vagrantfile` or via the `DOKKU_IP` environment variable - and are not using `10.0.0.2` for the Vagrant IP, you'll need to instead use the output of `vagrant ssh-config dokku` for your `~/.ssh/config` entry. 6. Connect to the server via `vagrant ssh` and add your ssh key to the install. Additionally, set the global domain name to `dokku.me`. diff --git a/docs/getting-started/installation/index.md b/docs/getting-started/installation/index.md index 10e45369f..8f0d32d06 100644 --- a/docs/getting-started/installation/index.md +++ b/docs/getting-started/installation/index.md @@ -1,10 +1,10 @@ # Getting Started with Dokku -### What is Dokku? +## What is Dokku? Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. Dokku supports building apps on the fly from a `git push` via either Dockerfile or by auto-detecting the language with Buildpacks, and then starts containers based on your built image. Using technologies such as nginx and cron, Web processes are automatically routed to, while background processes and automated cron tasks are also managed by Dokku. -### System Requirements +## System Requirements To start using Dokku, you'll need a system that meets the following minimum requirements: @@ -12,7 +12,7 @@ To start using Dokku, you'll need a system that meets the following minimum requ - [Ubuntu 20.04/22.04](https://www.ubuntu.com/download) - [Debian 10+ x64](https://www.debian.org/distrib/) - A server with one of the following architectures - - AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers + - AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers - ARMV7 (alternatively known as `armhf`), commonly used for Raspberry PI - ARMV8 (alternatively known as `arm64`), commonly used for Raspberry PI and AWS Graviton @@ -28,11 +28,11 @@ Finally, we recommend attaching at least one domain name to your server. This is Please see the [dns documentation](/docs/networking/dns.md) and [domains documentation](/docs/configuration/domains.md) for more details. -### Installing the latest stable version +## Installing the latest stable version -This is the simple method of installing Dokku. For alternative methods of installation, see the [advanced install guide](/docs/getting-started/advanced-installation.md#configuring). +This is the simple method of installing Dokku. For alternative methods of installation, see the [advanced install guide](/docs/getting-started/advanced-installation.md#configuring). -#### 1. Install Dokku +### 1. Install Dokku To install the latest stable version of Dokku, you can run the following shell commands: @@ -44,7 +44,7 @@ sudo DOKKU_TAG=v0.31.0 bash bootstrap.sh The installation process takes about 5-10 minutes, depending upon internet connection speed. -#### 2. Setup SSH key and Virtualhost Settings +### 2. Setup SSH key and Virtualhost Settings Once the installation is complete, you should configure an ssh key and set your global domain. @@ -67,6 +67,6 @@ dokku domains:set-global 10.0.0.2.sslip.io See the [user management](/docs/deployment/user-management.md#adding-ssh-keys) and [domains documentation](/docs/configuration/domains.md#customizing-hostnames) for more information. -#### 3. Deploy your first application +### 3. Deploy your first application At this point, you should be able to [deploy to the Dokku installation](/docs/deployment/application-deployment.md). diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md index 0b876d5e1..bd3f7f8ab 100644 --- a/docs/getting-started/troubleshooting.md +++ b/docs/getting-started/troubleshooting.md @@ -33,7 +33,7 @@ dokku trace:off ## Common Problems -### I deployed my app but I am getting the default nginx page. +### I deployed my app but I am getting the default nginx page Most of the time it's caused by some defaults newer versions of nginx set. To make sure that's the issue you're having run the following: @@ -91,7 +91,7 @@ The following error may be emitted from a deploy: The `remote rejected` error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue. -One the reasons why you may get this error is because the command that is run in the container exited (without errors). For example, (in Procfile) when you define a new worker container to run Delayed Job and use the bin/delayed_job start command. This command deamonizes the process and exists. The container thinks it's done so it closes itself. The error you get is the one above. To fix the above problem for Delayed Job, you must define the worker to user rake jobs:work, which doesn't deamonize the process. +One the reasons why you may get this error is because the command that is run in the container exited (without errors). For example, (in Procfile) when you define a new worker container to run Delayed Job and use the bin/delayed_job start command. This command deamonizes the process and exists. The container thinks it's done so it closes itself. The error you get is the one above. To fix the above problem for Delayed Job, you must define the worker to user rake jobs:work, which doesn't deamonize the process. ### I get the aforementioned error in the build phase (after turning on Dokku tracing) @@ -121,7 +121,7 @@ Sometimes (especially on DigitalOcean) deploying again seems to get past these s resolvconf -u ``` -Please see https://github.com/dokku/dokku/issues/841 and https://github.com/dokku/dokku/issues/649. +Please see [#841](https://github.com/dokku/dokku/issues/841) and [#649](https://github.com/dokku/dokku/issues/649). ### After adding an SSH key, I am told I cannot read from the remote repository on push @@ -155,7 +155,7 @@ Host DOKKU_HOSTNAME Also see [issue #116](https://github.com/dokku/dokku/issues/116). -### I successfully deployed my application with no deployment errors and receiving **Bad Gateway** when attempting to access the application. +### I successfully deployed my application with no deployment errors and receiving **Bad Gateway** when attempting to access the application In many cases the application will require the a `process.env.PORT` port opposed to a specified port. @@ -171,7 +171,7 @@ Additionally, your application should listen/bind to all interfaces (`0.0.0.0`). Please see [#5798](https://github.com/dokku/dokku/issues/5798). -### Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file`. +### Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file` If you see output similar this when deploying: @@ -191,11 +191,11 @@ dokku config:set --global CURL_TIMEOUT=1200 dokku config:set --global CURL_CONNECT_TIMEOUT=180 ``` -Please see https://github.com/dokku/dokku/issues/509. +Please see [#509](https://github.com/dokku/dokku/issues/509). Another reason for this error (although it may respond immediately ruling out a timeout issue) may be because you've set the config setting `SSL_CERT_FILE`. Using a config setting with this key interferes with the buildpack's ability to download its dependencies, so you must rename the config setting to something else, e.g. `MY_APP_SSL_CERT_FILE`. -### Build fails with `Killed` message. +### Build fails with `Killed` message This generally occurs when the server runs out of memory. You can either add more RAM to your server or setup swap space. The follow script will create 2 GB of swap space. @@ -209,7 +209,7 @@ sudo sysctl -w vm.swappiness=10 echo vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf ``` -### I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application. +### I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application This can occur if Dokku is running on a system with a firewall like UFW enabled (some OS versions like Ubuntu have this enabled by default). You can check if this is your case by running the following script: @@ -223,7 +223,7 @@ If the previous script returned `Status: active` and a list of ports, UFW is ena sudo ufw disable ``` -### I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection. +### I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection This isn't usually an issue with Dokku, but rather an app config problem. This can happen when your application is configured to enforce secure connections/HSTS, but you don't have SSL set up for the app. diff --git a/docs/networking/port-management.md b/docs/networking/port-management.md index 10d17a7ac..927f97f8a 100644 --- a/docs/networking/port-management.md +++ b/docs/networking/port-management.md @@ -28,8 +28,7 @@ The proxy port scheme is as follows: - `SCHEME:HOST_PORT:CONTAINER_PORT` -The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in `nginx-vhosts` proxy implementation supports the `http`, `https`, `grpc` and `grpcs` schemes. -For the `grpc` and `grpcs` see [nginx blog post on grpc](https://www.nginx.com/blog/nginx-1-13-10-grpc/). +The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in `nginx-vhosts` proxy implementation supports the `http`, `https`, `grpc` and `grpcs` schemes. For the `grpc` and `grpcs` see [nginx blog post on grpc](https://www.nginx.com/blog/nginx-1-13-10-grpc/). Developers of proxy implementations are encouraged to use whatever schemes make the most sense, and ignore configurations which they do not support. For instance, a `udp` proxy implementation can safely ignore `http` and `https` port mappings. diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md index 2c85783c5..7fb14c93e 100644 --- a/docs/networking/proxies/nginx.md +++ b/docs/networking/proxies/nginx.md @@ -107,7 +107,7 @@ Once the HSTS setting is disabled globally, it can be re-enabled on a per-app ba dokku nginx:set node-js-app hsts true ``` -### Running behind another proxy — configuring `X-Forwarded-*` headers: +### Running behind another proxy — configuring `X-Forwarded-*` headers Dokku's default Nginx configuration passes the de-facto standard HTTP headers [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), and `X-Forwarded-Port` to your application. These headers indicate the IP address of the original client making the request, the protocol of the original request (HTTP or HTTPS), and the port number of the original request, respectively. @@ -331,7 +331,6 @@ When deploying a monorepo, it may be desirable to specify the specific path of t 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 ``` diff --git a/docs/networking/proxy-management.md b/docs/networking/proxy-management.md index 4366acbe4..a07066541 100644 --- a/docs/networking/proxy-management.md +++ b/docs/networking/proxy-management.md @@ -117,36 +117,36 @@ From Dokku versions `0.5.0` until `0.11.0`, enabling or disabling an application Custom plugins names _must_ have the suffix `-vhosts` or scheduler overriding via `proxy:set` may not function as expected. -At this time, the following dokku commands are used to interact with a complete proxy implementation. +At this time, the following dokku commands are used to interact with a complete proxy implementation. - `domains:add`: Adds a given domain to an app. - - triggers: `post-domains-update` + - triggers: `post-domains-update` - `domains:clear`: Clears out an app's associated domains. - - triggers: `post-domains-update` + - triggers: `post-domains-update` - `domains:disable`: Disables domains for an app. - - triggers: `pre-disable-vhost` + - triggers: `pre-disable-vhost` - `domains:enable`: Enables domains for an app. - - triggers: `pre-enable-vhost` + - triggers: `pre-enable-vhost` - `domains:remove`: Removes a domain from an app. - - triggers: `post-domains-update` + - triggers: `post-domains-update` - `domains:set`: Sets all domains for a given app. - - triggers: `post-domains-update` + - triggers: `post-domains-update` - `proxy:build-config`: Builds - or rebuilds - external proxy configuration. - - triggers: `proxy-build-config` + - triggers: `proxy-build-config` - `proxy:clear-config`: Clears out external proxy configuration. - - triggers: `proxy-clear-config` + - triggers: `proxy-clear-config` - `proxy:disable`: Disables the proxy configuration for an app. - - triggers: `proxy-disable` + - triggers: `proxy-disable` - `proxy:enable`: Enables the proxy configuration for an app. - - triggers: `proxy-enable` + - triggers: `proxy-enable` - `ports:add`: Adds one or more port mappings to an app - - triggers: `post-proxy-ports-update` + - triggers: `post-proxy-ports-update` - `ports:clear`: Clears out all port mappings for an app. - - triggers: `post-proxy-ports-update` + - triggers: `post-proxy-ports-update` - `ports:remove`: Removes one or more port mappings from an app. - - triggers: `post-proxy-ports-update` + - triggers: `post-proxy-ports-update` - `ports:set`: Sets all port mappings for an app. - - triggers: `post-proxy-ports-update` + - triggers: `post-proxy-ports-update` Proxy implementations may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins. diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 9d3e5fbae..8485eb52d 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -117,7 +117,7 @@ If the file exists, it should not be empty, as doing so may result in a failed d The syntax for declaring a `Procfile` is as follows. Note that the format is one process type per line, with no duplicate process types. -``` +```Procfile : ``` @@ -141,7 +141,7 @@ For initial app deploys, Dokku will default to starting a single `web` process f There are also a few other exceptions for the `web` process. - By default, the built-in nginx proxy implementation only proxies the `web` process (others may be handled via a custom `nginx.conf.sigil`). - - See the [nginx request proxying documentation](/docs/networking/proxies/nginx.md#request-proxying) for more information on how nginx handles proxied requests. + - See the [nginx request proxying documentation](/docs/networking/proxies/nginx.md#request-proxying) for more information on how nginx handles proxied requests. - Only the `web` process may be bound to an external port. #### The `release` process @@ -206,7 +206,7 @@ dokku ps:scale --skip-deploy node-js-app web=1 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 +```json { "formation": { "web": { @@ -383,7 +383,7 @@ When a server reboots or Docker is restarted/upgraded, Docker may or may not sta - Start all linked services. - Clear generated proxy configuration files. - Start the app if it has not been manually stopped. - - If the app containers still exist, they will be started and the generated proxy configuration files will be rebuilt. - - If any of the app containers are missing, the entire app will be rebuilt. + - If the app containers still exist, they will be started and the generated proxy configuration files will be rebuilt. + - If any of the app containers are missing, the entire app will be rebuilt. During this time, requests may route to the incorrect app if the assigned IPs correspond to those for other apps. While dokku makes all efforts to avoid this, there may be a few minutes where urls may route to the wrong app. To avoid this, either use a custom proxy plugin or wait a few minutes until the restoration process is complete. diff --git a/docs/processes/scheduled-cron-tasks.md b/docs/processes/scheduled-cron-tasks.md index c53a97d8b..5dce920ac 100644 --- a/docs/processes/scheduled-cron-tasks.md +++ b/docs/processes/scheduled-cron-tasks.md @@ -18,7 +18,7 @@ Dokku automates scheduled `dokku run` commands via it's `app.json` cron integrat The `app.json` file for a given app can define a special `cron` key that contains a list of commands to run on given schedules. The following is a simple example `app.json` that effectively runs the command `dokku run $APP npm run send-email` once a day: -``` +```json { "cron": [ { @@ -168,8 +168,7 @@ For tasks that will properly resume, you _should_ use the above method, as runni Regularly scheduled tasks can be a bit of a pain with Dokku. The following are general recommendations to follow to help ensure successful task runs. - Use the `dokku` user in your cron entry. - - If you do not, the `dokku` binary will attempt to execute with `sudo`, and your cron run with fail with `sudo: no tty present and no askpass program specified`. - + - If you do not, the `dokku` binary will attempt to execute with `sudo`, and your cron run with fail with `sudo: no tty present and no askpass program specified`. - Add a `MAILTO` environment variable to ship cron emails to yourself. - Add a `PATH` environment variable or specify the full path to binaries on the host. - Add a `SHELL` environment variable to specify Bash when running commands. diff --git a/tests/apps/multi/README.md b/tests/apps/multi/README.md index cba503104..c940a583d 100644 --- a/tests/apps/multi/README.md +++ b/tests/apps/multi/README.md @@ -1,3 +1,3 @@ -This is a sample application to test heroku buildpack multi for integrating with herokuish: https://github.com/gliderlabs/herokuish +This is a sample application to test heroku buildpack multi for integrating with [herokuish](https://github.com/gliderlabs/herokuish) I am choosing to use the python, nodejs, and ruby buildpacks to create a very simple flask app that performs a bower install and a simple grunt task using compass. diff --git a/tests/apps/scala/README.md b/tests/apps/scala/README.md index 67d57f50b..177853c88 100644 --- a/tests/apps/scala/README.md +++ b/tests/apps/scala/README.md @@ -9,10 +9,10 @@ This application support the [Getting Started with Scala on Heroku](https://devc Make sure you have Scala and sbt installed. Also, install the [Heroku Toolbelt](https://toolbelt.heroku.com/). ```sh -$ git clone https://github.com/heroku/scala-getting-started.git -$ cd scala-getting-started -$ sbt compile stage -$ foreman start web +git clone https://github.com/heroku/scala-getting-started.git +cd scala-getting-started +sbt compile stage +foreman start web ``` Your app should now be running on [localhost:5000](http://localhost:5000/). @@ -20,9 +20,9 @@ Your app should now be running on [localhost:5000](http://localhost:5000/). ## Deploying to Heroku ```sh -$ heroku create -$ git push heroku master -$ heroku open +heroku create +git push heroku master +heroku open ``` ## Documentation @@ -30,4 +30,3 @@ $ heroku open For more information about using Scala on Heroku, see these Dev Center articles: - [Scala on Heroku](https://devcenter.heroku.com/categories/scala) - From d61d91cf87fbc7fa8643a4e64325ba8490641370 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 19 Aug 2023 14:24:12 -0400 Subject: [PATCH 2/5] docs: use github admonitions These still need to be properly parsed. --- HISTORY.md | 3 +- docs/advanced-usage/backup-recovery.md | 3 +- docs/advanced-usage/deployment-tasks.md | 9 ++- docs/advanced-usage/docker-options.md | 5 +- docs/advanced-usage/event-logs.md | 1 + docs/advanced-usage/persistent-storage.md | 13 +++- docs/advanced-usage/plugin-management.md | 7 +- docs/advanced-usage/registry-management.md | 1 + docs/advanced-usage/repository-management.md | 1 + docs/advanced-usage/resource-management.md | 4 +- docs/community/plugins.md | 3 +- docs/configuration/domains.md | 2 + docs/configuration/environment-variables.md | 6 +- docs/configuration/ssl.md | 8 +- docs/deployment/application-deployment.md | 15 ++-- docs/deployment/application-management.md | 14 +++- .../deployment/builders/builder-management.md | 4 +- .../builders/cloud-native-buildpacks.md | 6 +- docs/deployment/builders/dockerfiles.md | 3 + .../builders/herokuish-buildpacks.md | 7 +- docs/deployment/builders/lambda.md | 1 + docs/deployment/builders/null.md | 1 + docs/deployment/logs.md | 7 +- docs/deployment/methods/git.md | 13 +++- docs/deployment/schedulers/docker-local.md | 4 + docs/deployment/schedulers/kubernetes.md | 3 +- docs/deployment/schedulers/nomad.md | 6 +- docs/deployment/schedulers/null.md | 1 + .../schedulers/scheduler-management.md | 1 + docs/deployment/user-management.md | 3 + docs/deployment/zero-downtime-deploys.md | 6 +- docs/development/plugin-creation.md | 4 + docs/development/plugin-triggers.md | 78 ++++++++++++------- docs/getting-started/troubleshooting.md | 1 + docs/networking/dns.md | 3 +- docs/networking/network.md | 13 +++- docs/networking/port-management.md | 10 ++- docs/networking/proxies/caddy.md | 4 +- docs/networking/proxies/haproxy.md | 4 +- docs/networking/proxies/nginx.md | 54 +++++++++---- docs/networking/proxies/openresty.md | 4 +- docs/networking/proxies/traefik.md | 10 ++- docs/networking/proxy-management.md | 3 + docs/processes/entering-containers.md | 1 + docs/processes/one-off-tasks.md | 5 ++ docs/processes/process-management.md | 7 +- docs/processes/scheduled-cron-tasks.md | 4 +- 47 files changed, 277 insertions(+), 89 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 1cb8993a2..82bfe5595 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -2869,7 +2869,8 @@ sudo DOKKU_TAG=v0.21.1 bash bootstrap.sh ## 0.21.0 -> Warning: Release is broken and will be pulled from upstream. Please use a newer version. +> [!WARNING] +> Release is broken and will be pulled from upstream. Please use a newer version. ### Bug Fixes diff --git a/docs/advanced-usage/backup-recovery.md b/docs/advanced-usage/backup-recovery.md index df487834b..13b2cc84d 100644 --- a/docs/advanced-usage/backup-recovery.md +++ b/docs/advanced-usage/backup-recovery.md @@ -6,7 +6,8 @@ The best plan for disaster recovery is to always keep multiple (remote) copies o ## TLDR -> Warning: This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis. +> [!WARNING] +> This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis. ### Creating a backup diff --git a/docs/advanced-usage/deployment-tasks.md b/docs/advanced-usage/deployment-tasks.md index c93b7c456..ee62d4f70 100644 --- a/docs/advanced-usage/deployment-tasks.md +++ b/docs/advanced-usage/deployment-tasks.md @@ -1,5 +1,6 @@ # Deployment Tasks +> [!IMPORTANT] > New as of 0.5.0 ## Usage @@ -83,6 +84,7 @@ dokku app-json:set --global appjson-path ### Displaying app-json reports for an app +> [!IMPORTANT] > New as of 0.25.0 You can get a report about the app's storage status using the `app-json:report` command: @@ -139,7 +141,8 @@ 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. -> 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. +> [!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. @@ -157,6 +160,7 @@ The following is an example `app.json` file. Please note that only the `scripts. #### Procfile Release command +> [!IMPORTANT] > New as of 0.14.0 The `Procfile` also supports a special `release` command which acts in a similar way to the [Heroku Release Phase](https://devcenter.heroku.com/articles/release-phase). This command is executed _after_ an app's docker image is built, but _before_ any containers are scheduled. This is also run _after_ any command executed by `scripts.dokku.predeploy`. @@ -169,4 +173,5 @@ release: curl https://some.external.api.service.com/deployment?state=built Unlike the `scripts.dokku.predeploy` command, changes made during by the `release` command are _not_ persisted to disk. -> Warning: scaling the release command up will likely result in unspecified issues within your deployment, and is highly discouraged. +> [!WARNING] +> scaling the release command up will likely result in unspecified issues within your deployment, and is highly discouraged. diff --git a/docs/advanced-usage/docker-options.md b/docs/advanced-usage/docker-options.md index 153e499cd..b9ef3f55f 100644 --- a/docs/advanced-usage/docker-options.md +++ b/docs/advanced-usage/docker-options.md @@ -1,5 +1,6 @@ # Docker Container Options +> [!IMPORTANT] > New as of 0.3.17 Pass [container options](https://docs.docker.com/engine/reference/run/) to the `docker run` command during Dokku's `build`, `deploy` and `run` phases @@ -43,7 +44,8 @@ dokku docker-options:add node-js-app deploy "-v /var/log/node-js-app:/app/logs" dokku docker-options:add node-js-app run "-v /var/log/node-js-app:/app/logs" ``` -> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory. +> [!NOTE] +> When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory. ### Remove a Docker option @@ -84,6 +86,7 @@ dokku docker-options:clear node-js-app build,run ### Displaying docker-options reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's docker-options status using the `docker-options:report` command: diff --git a/docs/advanced-usage/event-logs.md b/docs/advanced-usage/event-logs.md index fc05b869a..68b8336a5 100644 --- a/docs/advanced-usage/event-logs.md +++ b/docs/advanced-usage/event-logs.md @@ -1,5 +1,6 @@ # Dokku Event Logs +> [!IMPORTANT] > New as of 0.3.21 Docker provides an _events_ command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones. diff --git a/docs/advanced-usage/persistent-storage.md b/docs/advanced-usage/persistent-storage.md index 580764bfa..646519310 100644 --- a/docs/advanced-usage/persistent-storage.md +++ b/docs/advanced-usage/persistent-storage.md @@ -1,5 +1,6 @@ # Persistent Storage +> [!IMPORTANT] > New as of 0.5.0 The preferred method to mount external containers to a Dokku managed container, is to use the Dokku storage plugin. @@ -52,6 +53,7 @@ dokku storage:list node-js-app --format json ### Creating storage directories +> [!IMPORTANT] > New as of 0.25.5 A storage directory can be created with the `storage:ensure-directory` command. This command will create a subdirectory in the recommended `/var/lib/dokku/data/storage` path - created during Dokku installation - and prepare it for use with an app. @@ -78,7 +80,8 @@ By default, permissions are set for usage with Herokuish buildpacks. These permi Users deploying via Dockerfile will want to specify `--chown false` and manually `chown` the created directory if the user and/or group id of the runnning process in the deployed container do not correspond to any of the above options. -> Warning: Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory. +> [!WARNING] +> Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory. ### Mounting storage into apps @@ -124,6 +127,7 @@ dokku ps:restart app-name ### Displaying storage reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's storage status using the `storage:report` command: @@ -194,14 +198,17 @@ dokku docker-options:add node-js-app build "-v /tmp/python-test:/opt/test" You cannot use mounted volumes during the build phase of a Dockerfile deploy. This is because Docker does not support volumes when executing `docker build`. -> Warning: **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase. +> [!WARNING] +> **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase. ## App User and Persistent Storage file ownership (buildpack apps only) +> [!IMPORTANT] > New as of 0.7.1 By default, Dokku will execute your buildpack app processes as the `herokuishuser` user. You may override this by setting the `DOKKU_APP_USER` config variable. -> NOTE: this user must exist in your herokuish image. +> [!NOTE] +> this user must exist in your herokuish image. Additionally, the default `docker-local` scheduler that comes with Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. See the [docker-local scheduler documentation](/docs/deployment/schedulers/docker-local.md#disabling-chown-of-persistent-storage) docs for more information. diff --git a/docs/advanced-usage/plugin-management.md b/docs/advanced-usage/plugin-management.md index a3b861411..6caa10c7c 100644 --- a/docs/advanced-usage/plugin-management.md +++ b/docs/advanced-usage/plugin-management.md @@ -1,5 +1,6 @@ # Plugin Management +> [!IMPORTANT] > New as of 0.4.0 ``` @@ -66,7 +67,8 @@ plugn: dev trace 0.31.0 enabled dokku core trace plugin ``` -> Warning: All plugin commands other than `plugin:list` and `plugin:help` require sudo access and must be run directly from the Dokku server. +> [!WARNING] +> All plugin commands other than `plugin:list` and `plugin:help` require sudo access and must be run directly from the Dokku server. ### Checking if a plugin is installed @@ -78,7 +80,8 @@ dokku plugin:installed postgres ### Installing a plugin -> Note: Plugins installed in this method within a [docker-based installation](/docs/getting-started/install/docker.md) of Dokku do not persist across installs. Please see the [plugin installation section](/docs/getting-started/install/docker.md#plugin-installation) of the docker-based installation docs for further details. +> [!NOTE] +> Plugins installed in this method within a [docker-based installation](/docs/getting-started/install/docker.md) of Dokku do not persist across installs. Please see the [plugin installation section](/docs/getting-started/install/docker.md#plugin-installation) of the docker-based installation docs for further details. Installing a plugin is easy as well using the `plugin:install` command. This command will also trigger the `install` pluginhook on all existing plugins. diff --git a/docs/advanced-usage/registry-management.md b/docs/advanced-usage/registry-management.md index 4b956a586..9ffd07896 100644 --- a/docs/advanced-usage/registry-management.md +++ b/docs/advanced-usage/registry-management.md @@ -1,5 +1,6 @@ # Registry Management +> [!IMPORTANT] > New as of 0.25.0 ``` diff --git a/docs/advanced-usage/repository-management.md b/docs/advanced-usage/repository-management.md index e8235f863..5e1c67ccf 100644 --- a/docs/advanced-usage/repository-management.md +++ b/docs/advanced-usage/repository-management.md @@ -1,5 +1,6 @@ # Repository Management +> [!IMPORTANT] > New as of 0.6.0 ``` diff --git a/docs/advanced-usage/resource-management.md b/docs/advanced-usage/resource-management.md index bcbe07a91..e24b56b32 100644 --- a/docs/advanced-usage/resource-management.md +++ b/docs/advanced-usage/resource-management.md @@ -1,5 +1,6 @@ # Resource Management +> [!IMPORTANT] > New as of 0.15.0 ``` @@ -16,7 +17,8 @@ The resource plugin is meant to allow users to limit or reserve resources for a By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The `resource` plugin allows management of both resource "limits" and resource "reservations", where each resource request type has specific meaning to the scheduler in use for a given app. -> Warning: The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect. +> [!WARNING] +> The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect. Valid resource options include: diff --git a/docs/community/plugins.md b/docs/community/plugins.md index da144aeab..a2344c929 100644 --- a/docs/community/plugins.md +++ b/docs/community/plugins.md @@ -46,7 +46,8 @@ The following plugins are available and provided by Dokku maintainers. Please f ## Community plugins -> Warning: The following plugins have been supplied by our community and may not have been tested by Dokku maintainers. +> [!WARNING] +> The following plugins have been supplied by our community and may not have been tested by Dokku maintainers. ### Datastores diff --git a/docs/configuration/domains.md b/docs/configuration/domains.md index 28057375a..ef815b620 100644 --- a/docs/configuration/domains.md +++ b/docs/configuration/domains.md @@ -1,5 +1,6 @@ # Domain Configuration +> [!IMPORTANT] > New as of 0.3.10 ``` @@ -65,6 +66,7 @@ dokku domains:set node-js-app dokku.me dokku.org ## Displaying domains reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's domains status using the `domains:report` command: diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index cdcb804cd..508a649cf 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -21,7 +21,8 @@ Environment variables are available both at run time and during the application For buildpack deploys, Dokku will create a `/app/.env` file that can be used for legacy buildpacks. Note that this is _not_ updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then. -> Note: Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications. +> [!NOTE] +> Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications. You can set multiple environment variables at once: @@ -74,7 +75,8 @@ dokku config:export --format shell node-js-app The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future. -> Warning: This list is not exhaustive, and may vary from version to version. +> [!WARNING] +> This list is not exhaustive, and may vary from version to version. | Name | Default | How to modify | Description | | ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | diff --git a/docs/configuration/ssl.md b/docs/configuration/ssl.md index abb0f9f62..7581acea8 100644 --- a/docs/configuration/ssl.md +++ b/docs/configuration/ssl.md @@ -1,5 +1,6 @@ # SSL Configuration +> [!IMPORTANT] > New as of 0.4.0 Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled. @@ -33,7 +34,8 @@ tar cvf cert-key.tar server.crt server.key dokku certs:add node-js-app < cert-key.tar ``` -> Note: If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`. +> [!NOTE] +> If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`. ```shell cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt @@ -47,7 +49,8 @@ Note that with the default nginx template, requests will be redirected to the `h ### Certificate generation -> Note: Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments. +> [!NOTE] +> Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments. The `certs:generate` command will walk you through the correct `openssl` commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration. @@ -69,6 +72,7 @@ dokku certs:show node-js-app key > server.key ### Displaying certificate reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the apps ssl status using the `certs:report` command: diff --git a/docs/deployment/application-deployment.md b/docs/deployment/application-deployment.md index 66522eb46..3c61a2c90 100644 --- a/docs/deployment/application-deployment.md +++ b/docs/deployment/application-deployment.md @@ -1,6 +1,7 @@ # Deploying an Application -> Note: This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should substitute the domain `dokku.me` for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use `dokku.me` which points to the IP of the VM. +> [!NOTE] +> This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should substitute the domain `dokku.me` for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use `dokku.me` which points to the IP of the VM. ## Deploy tutorial @@ -52,7 +53,8 @@ Dokku supports linking a single service to multiple applications as well as link ### Deploy the app -> Warning: Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).** +> [!WARNING] +> Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).** Now you can deploy the `ruby-getting-started` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server. @@ -64,11 +66,13 @@ git remote add dokku dokku@dokku.me:ruby-getting-started git push dokku main ``` -> Note: Some tools may not support the short-upstream syntax referenced above, and you may need to prefix +> [!NOTE] +> Some tools may not support the short-upstream syntax referenced above, and you may need to prefix > the upstream with the scheme `ssh://` like so: `ssh://dokku@dokku.me:ruby-getting-started` > Please see the [Git](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) documentation for more details. -> Note: Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/`. +> [!NOTE] +> Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/`. After running `git push dokku main`, you should have output similar to this in your terminal: @@ -168,7 +172,8 @@ ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts ssh -T git@github.com ``` -> Warning: if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply. +> [!WARNING] +> if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply. ## Deploying to subdomains diff --git a/docs/deployment/application-management.md b/docs/deployment/application-management.md index 7f22cb761..ca5743e58 100644 --- a/docs/deployment/application-management.md +++ b/docs/deployment/application-management.md @@ -1,5 +1,6 @@ # Application Management +> [!IMPORTANT] > New as of 0.3.1 ``` @@ -19,6 +20,7 @@ apps:unlock # Unlocks an app for deployment ### Listing applications +> [!IMPORTANT] > New as of 0.8.1. Use the `apps` command for older versions. You can easily list all available applications using the `apps:list` command: @@ -117,6 +119,7 @@ Destroying an application will unlink all linked services and destroy any config ### Renaming a deployed app +> [!IMPORTANT] > New as of 0.4.7 You can rename a deployed app using the `apps:rename` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully: @@ -158,6 +161,7 @@ git remote set-url dokku dokku@dokku.me:io-js-app ### Cloning an existing app +> [!IMPORTANT] > New as of 0.11.5 You can clone an existing app using the `apps:clone` command. Note that the application *must* have been deployed at least once, or cloning will not complete successfully: @@ -177,7 +181,8 @@ This will copy all of your app's contents into a new app directory with the name - SSL certificates will not be copied to the new app. - Port mappings with the scheme `https` and host-port `443` will be skipped. -> Warning: If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors. +> [!WARNING] +> If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors. By default, Dokku will deploy this new app, though you can skip the deploy by using the `--skip-deploy` flag: @@ -193,6 +198,7 @@ dokku apps:clone --ignore-existing node-js-app io-js-app ### Locking app deploys +> [!IMPORTANT] > New as of 0.11.6 If you wish to disable deploying for a period of time, this can be done via deploy locks. Normally, deploy locks exist only for the duration of a deploy so as to avoid deploys from colliding, but a deploy lock can be created by running the `apps:lock` command. @@ -207,11 +213,13 @@ dokku apps:lock node-js-app ### Unlocking app deploys +> [!IMPORTANT] > New as of 0.11.6 In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the `apps:unlock` command. -> Warning: Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access. +> [!WARNING] +> Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access. ```shell dokku apps:unlock node-js-app @@ -225,6 +233,7 @@ dokku apps:unlock node-js-app ### Checking lock status +> [!IMPORTANT] > New as of 0.13.0 In some cases, you may wish to inspect the state of an app lock. To do so, you can issue an `apps:lock` command. This will exit non-zero if there is no app lock in place. @@ -239,6 +248,7 @@ Deploy lock does not exist ### Displaying reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the deployed apps using the `apps:report` command: diff --git a/docs/deployment/builders/builder-management.md b/docs/deployment/builders/builder-management.md index d05df624d..fc334ed8a 100644 --- a/docs/deployment/builders/builder-management.md +++ b/docs/deployment/builders/builder-management.md @@ -1,5 +1,6 @@ # Builder Management +> [!IMPORTANT] > New as of 0.24.0 ``` @@ -51,7 +52,8 @@ dokku builder:set --global selected #### Changing the build directory -> Warning: Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the `git.keep-git-dir` property. +> [!WARNING] +> Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the `git.keep-git-dir` property. When deploying a monorepo, it may be desirable to specify the specific build directory to use for a given app. This can be done via the `builder:set` command. If a value is specified and that directory does not exist within the repository, the build will fail. diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index 718909a58..1a30cf704 100644 --- a/docs/deployment/builders/cloud-native-buildpacks.md +++ b/docs/deployment/builders/cloud-native-buildpacks.md @@ -1,5 +1,6 @@ # Cloud Native Buildpacks +> [!IMPORTANT] > New as of 0.22.0 ``` @@ -13,7 +14,8 @@ buildpacks:set-property [--global|] # Set or clear a buildpa Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the [herokuish buildpacks documentation](/docs/deployment/builders/herokuish-buildpacks.md) for more information on how to clear buildpack build cache for an application. -> Warning: This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time. +> [!WARNING] +> This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time. ## Usage @@ -88,6 +90,7 @@ dokku builder-pack:set --global projecttoml-path ### Displaying builder-pack reports for an app +> [!IMPORTANT] > New as of 0.25.0 You can get a report about the app's storage status using the `builder-pack:report` command: @@ -136,6 +139,7 @@ project2.toml ### Customizing the Buildpack stack builder +> [!IMPORTANT] > New as of 0.23.0 The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:22`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command. diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index 62a1cc590..8b6702c8f 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -1,5 +1,6 @@ # Dockerfile Deployment +> [!IMPORTANT] > New as of 0.3.15 ``` @@ -64,6 +65,7 @@ dokku builder-dockerfile:set --global dockerfile-path ### Displaying builder-dockerfile reports for an app +> [!IMPORTANT] > New as of 0.25.0 You can get a report about the app's storage status using the `builder-dockerfile:report` command: @@ -196,6 +198,7 @@ Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disa ### Procfiles and multiple processes +> [!IMPORTANT] > New as of 0.5.0 See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app. diff --git a/docs/deployment/builders/herokuish-buildpacks.md b/docs/deployment/builders/herokuish-buildpacks.md index b9f07beb6..29974f2f6 100644 --- a/docs/deployment/builders/herokuish-buildpacks.md +++ b/docs/deployment/builders/herokuish-buildpacks.md @@ -1,5 +1,6 @@ # Herokuish Buildpacks +> [!IMPORTANT] > Subcommands new as of 0.15.0 ``` @@ -17,7 +18,8 @@ builder-herokuish:report [] [] # Displays a builder-herokuish repor builder-herokuish:set () # Set or clear a builder-herokuish property for an app ``` -> Warning: If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin. +> [!WARNING] +> If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin. Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following: @@ -147,6 +149,7 @@ dokku buildpacks:clear node-js-app ### Customizing the Buildpack stack builder +> [!IMPORTANT] > New as of 0.23.0 The default stack builder in use by Herokuish buildpacks in Dokku is based on `gliderlabs/herokuish:latest`. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command. @@ -175,6 +178,7 @@ dokku buildpacks:set-property --global stack ### Allowing herokuish for non-amd64 platforms +> [!IMPORTANT] > New as of 0.29.0 By default, the builder-herokuish plugin is not enabled for non-amd64 platforms, and attempting to use it is blocked. This is because the majority of buildpacks are not cross-platform compatible, and thus building apps will either be considerably slower - due to emulating the amd64 platform - or won't work - due to building amd64 packages on arm/arm64 platforms. @@ -248,6 +252,7 @@ dokku buildpacks:report node-js-app --buildpacks-list ### Displaying builder-herokuish reports for an app +> [!IMPORTANT] > New as of 0.29.0 You can get a report about the app's storage status using the `builder-herokuish:report` command: diff --git a/docs/deployment/builders/lambda.md b/docs/deployment/builders/lambda.md index 692268c07..9df4501c6 100644 --- a/docs/deployment/builders/lambda.md +++ b/docs/deployment/builders/lambda.md @@ -1,5 +1,6 @@ # Lambda Builder +> [!IMPORTANT] > New as of 0.28.0 ``` diff --git a/docs/deployment/builders/null.md b/docs/deployment/builders/null.md index 88a1b2f2d..095f75cdf 100644 --- a/docs/deployment/builders/null.md +++ b/docs/deployment/builders/null.md @@ -1,5 +1,6 @@ # Null Builder +> [!IMPORTANT] > New as of 0.25.0 The `null` builder does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the [network documentation](/docs/networking/network.md#routing-an-app-to-a-known-ip:port-combination) for more information on the aforementioned use case. diff --git a/docs/deployment/logs.md b/docs/deployment/logs.md index 8c9531893..178f0131a 100644 --- a/docs/deployment/logs.md +++ b/docs/deployment/logs.md @@ -43,7 +43,8 @@ The above command will show logs continually from the web process. ### Failed deploy logs -> Warning: The default [docker-local scheduler](/docs/deployment/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server. +> [!WARNING] +> The default [docker-local scheduler](/docs/deployment/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server. In some cases, it may be useful to retrieve the logs from a previously failed deploy. @@ -89,13 +90,15 @@ dokku logs:set --global max-size ### Vector Logging Shipping +> [!IMPORTANT] > New as of 0.22.6 Vector is an open-source, lightweight and ultra-fast tool for building observability pipelines. Dokku integrates with it for shipping container logs for the `docker-local` scheduler. Users may configure log-shipping on a per-app or global basis, neither of which interfere with the `dokku logs` commands. #### Starting the Vector container -> Warning: While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected. +> [!WARNING] +> While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected. Vector may be started via the `logs:vector-start` command. diff --git a/docs/deployment/methods/git.md b/docs/deployment/methods/git.md index 3088294f1..3d7d79075 100644 --- a/docs/deployment/methods/git.md +++ b/docs/deployment/methods/git.md @@ -1,5 +1,6 @@ # Git Deployment +> [!IMPORTANT] > Subcommands new as of 0.12.0 ``` @@ -25,7 +26,8 @@ Git-based deployment has been the traditional method of deploying applications i ## Usage -> Warning: Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process. +> [!WARNING] +> Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process. ### Initializing an application @@ -40,7 +42,8 @@ dokku git:initialize node-js-app In order for the above command to succeed, the application _must_ already exist. -> Warning: If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku. +> [!WARNING] +> If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku. ### Changing the deploy branch @@ -72,6 +75,7 @@ Pushing multiple branches can also be supported by creating a [receive-branch](/ ### Configuring the `GIT_REV` environment variable +> [!IMPORTANT] > New as of 0.12.0 Application deployments will include a special `GIT_REV` environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same. @@ -123,6 +127,7 @@ Please keep in mind that setting `keep-git-dir` to `true` may result in unstaged ### 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. @@ -170,6 +175,7 @@ See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to ### 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. @@ -202,6 +208,7 @@ curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke- ### 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. @@ -245,6 +252,7 @@ See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to ### Initializing an app repository from a remote repository +> [!IMPORTANT] > New as of 0.23.0 A Dokku app repository can be initialized or updated from a remote git repository via the `git:sync` command. This command will either clone or fetch updates from a remote repository and has undefined behavior if the history cannot be fast-fowarded to the referenced repository reference. Any repository that can be cloned by the `dokku` user can be specified. @@ -276,6 +284,7 @@ dokku git:sync --build node-js-app https://github.com/heroku/node-js-getting-sta ### Initializing from private repositories +> [!IMPORTANT] > New as of 0.24.0 Initializing from a private repository requires one of the following: diff --git a/docs/deployment/schedulers/docker-local.md b/docs/deployment/schedulers/docker-local.md index 5da54e1c5..3cec7cd75 100644 --- a/docs/deployment/schedulers/docker-local.md +++ b/docs/deployment/schedulers/docker-local.md @@ -1,5 +1,6 @@ # Docker Local Scheduler +> [!IMPORTANT] > Subcommands new as of 0.12.12 ``` @@ -7,6 +8,7 @@ scheduler-docker-local:report [] [] # Displays a schedul scheduler-docker-local:set () # Set or clear a scheduler-docker-local property for an app ``` +> [!IMPORTANT] > New as of 0.12.0 Dokku natively includes functionality to manage application lifecycles for a single server using the `scheduler-docker-local` plugin. It is the default scheduler, but as with all schedulers, it is set on a per-application basis. The scheduler can currently be overridden by running the following command: @@ -55,6 +57,7 @@ All image containers with the label `org.opencontainers.image.vendor=linuxserver ### Deploying Process Types in Parallel +> [!IMPORTANT] > New as of 0.25.5 By default, Dokku deploys an app's processes one-by-one in order, with the `web` process being deployed first. Deployment parallelism may be achieved by setting the `parallel-schedule-count` property, which defaults to `1`. Increasing this number increases the number of process types that may be deployed in parallel (with the web process being the exception). @@ -78,6 +81,7 @@ Note that increasing the value of `parallel-schedule-count` may significantly im #### Increasing parallelism within a process deploy +> [!IMPORTANT] > New as of 0.26.0 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. diff --git a/docs/deployment/schedulers/kubernetes.md b/docs/deployment/schedulers/kubernetes.md index 441ebe99e..dcc253f43 100644 --- a/docs/deployment/schedulers/kubernetes.md +++ b/docs/deployment/schedulers/kubernetes.md @@ -1,6 +1,7 @@ # Kubernetes Scheduler -> Warning: This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. +> [!WARNING] +> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. The [Kubernetes Scheduler Plugin](https://github.com/dokku/dokku-scheduler-kubernetes) is available free as an external plugin. Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-kubernetes/issues) for more information on the status of the plugin. diff --git a/docs/deployment/schedulers/nomad.md b/docs/deployment/schedulers/nomad.md index 287185dd3..95de76e9c 100644 --- a/docs/deployment/schedulers/nomad.md +++ b/docs/deployment/schedulers/nomad.md @@ -1,6 +1,7 @@ # Nomad Scheduler -> Warning: This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. +> [!WARNING] +> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes. The [Nomad Scheduler Plugin](https://github.com/dokku/dokku-scheduler-nomad) is available free as an external plugin. Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-nomad/issues) for more information on the status of the plugin. @@ -20,4 +21,5 @@ This plugin implements various functionality through `plugn` triggers to integra ### Logging support -> Warning: Fetching app logs for the `logs` command is currently not implemented. Please consider using [Vector](https://vector.dev/docs/setup/installation/platforms/kubernetes/) or a similar tool to ship logs to another service or a third-party platform. +> [!WARNING] +> Fetching app logs for the `logs` command is currently not implemented. Please consider using [Vector](https://vector.dev/docs/setup/installation/platforms/kubernetes/) or a similar tool to ship logs to another service or a third-party platform. diff --git a/docs/deployment/schedulers/null.md b/docs/deployment/schedulers/null.md index b17ba5c91..eeb9bb6ab 100644 --- a/docs/deployment/schedulers/null.md +++ b/docs/deployment/schedulers/null.md @@ -1,5 +1,6 @@ # Null Scheduler +> [!IMPORTANT] > New as of 0.25.0 The `null` scheduler does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the [network documentation](/docs/networking/network.md#routing-an-app-to-a-known-ip:port-combination) for more information on the aforementioned use case. diff --git a/docs/deployment/schedulers/scheduler-management.md b/docs/deployment/schedulers/scheduler-management.md index 04da2bc81..3b93e614c 100644 --- a/docs/deployment/schedulers/scheduler-management.md +++ b/docs/deployment/schedulers/scheduler-management.md @@ -1,5 +1,6 @@ # Scheduler Management +> [!IMPORTANT] > New as of 0.26.0 ``` diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index 8685bf56c..27922f67c 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -1,5 +1,6 @@ # User Management +> [!IMPORTANT] > New as of 0.7.0 ``` @@ -34,6 +35,7 @@ The output contains the following information: - The `KEY_NAME`. - A comma separated list of SSH options under the `SSHCOMMAND_ALLOWED_KEYS` name. +> [!IMPORTANT] > New as of 0.20.2 The keys for a specific user may be listed by specifying a second argument to the `ssh-keys:list` command: @@ -42,6 +44,7 @@ The keys for a specific user may be listed by specifying a second argument to th dokku ssh-keys:list admin ``` +> [!IMPORTANT] > New as of 0.22.3 The output format may be specified via the `--format` flag. Supported values include `json` and `text`. diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 53ca0e444..d37118f03 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -1,5 +1,6 @@ # Zero Downtime Deploy Checks +> [!IMPORTANT] > New as of 0.5.0 ``` @@ -83,6 +84,7 @@ dokku checks:disable node-js-app worker ### Displaying checks reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's checks status using the `checks:report` command: @@ -135,6 +137,7 @@ dokku checks:report node-js-app --checks-disabled-list ## Customizing checks +> [!IMPORTANT] > New as of 0.31.0 If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use Dokku's `checks` functionality to more precisely check whether an application can serve traffic or not. @@ -171,7 +174,8 @@ A healthcheck entry takes the following properties: - `uptime`: (default: `""` - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries. - `wait`: (default: `5` seconds): Number of seconds to wait between healthcheck attempts. -> Warning: Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported. +> [!WARNING] +> Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported. See the [docker-container-healthchecker](https://github.com/dokku/docker-container-healthchecker) documentation for more details on how healthchecks are interpreted. diff --git a/docs/development/plugin-creation.md b/docs/development/plugin-creation.md index edebfc649..5370b973d 100644 --- a/docs/development/plugin-creation.md +++ b/docs/development/plugin-creation.md @@ -145,6 +145,7 @@ Any functions that must be kept private should reside in the plugin's `trigger/` ### Use helper functions to fetch app images +> [!IMPORTANT] > New as of 0.4.0 Dokku allows image tagging and deployment of tagged images. This means hard-coding the `$IMAGE` as `dokku/$APP` is no longer sufficient. @@ -155,6 +156,7 @@ Plugins should use `get_running_image_tag()` and `get_app_image_name()` as sourc ### Use `$DOCKER_BIN` instead of `docker` directly +> [!IMPORTANT] > New as of 0.17.5 Certain systems may require a wrapper function around the `docker` binary for proper execution. Utilizing the `$DOCKER_BIN` environment variable when calling docker for those functions is preferred. @@ -169,6 +171,7 @@ docker run -d $IMAGE /bin/bash -e -c "$COMMAND" ### Include labels for all temporary containers and images +> [!IMPORTANT] > New as of 0.5.0 As of 0.5.0, labels are used to help cleanup intermediate containers with `dokku cleanup`. Plugins that create containers and images should add the correct labels to the `build`, `commit`, and `run` docker commands. @@ -208,6 +211,7 @@ Files are copied from the `/app` directory - for images built via buildpacks - o ### Avoid calling the `dokku` binary directly +> [!IMPORTANT] > New as of 0.6.0 Plugins should **not** call the `dokku` binary directly from within plugins because clients using the `--app` argument are potentially broken when doing so. diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index 92e882b35..75a796aef 100644 --- a/docs/development/plugin-triggers.md +++ b/docs/development/plugin-triggers.md @@ -646,7 +646,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `docker-args-build` -> Warning: Deprecated, please use `docker-args-process-build` instead +> [!WARNING] +> Deprecated, please use `docker-args-process-build` instead - Description: - Invoked by: `internal function dokku_build() (build phase)` @@ -671,7 +672,8 @@ echo -n "$STDIN$output" ### `docker-args-deploy` -> Warning: Deprecated, please use `docker-args-process-deploy` instead +> [!WARNING] +> Deprecated, please use `docker-args-process-deploy` instead - Description: - Invoked by: `dokku deploy` @@ -742,7 +744,8 @@ APP="$1"; IMAGE_SOURCE_TYPE="$3"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $AP ### `docker-args-run` -> Warning: Deprecated, please use `docker-args-process-run` instead +> [!WARNING] +> Deprecated, please use `docker-args-process-run` instead - Description: - Invoked by: `dokku run` @@ -969,7 +972,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x # TODO ``` -> Warning: The `git-pre-pull` trigger should _not_ be used for authentication since it does not get called for commands that use `git-upload-archive` such as `git archive`. Instead, use the [`user-auth`](#user-auth) trigger. +> [!WARNING] +> The `git-pre-pull` trigger should _not_ be used for authentication since it does not get called for commands that use `git-upload-archive` such as `git archive`. Instead, use the [`user-auth`](#user-auth) trigger. ### `git-revision` @@ -1224,7 +1228,8 @@ echo "$NEW_SUBDOMAIN.$VHOST" ### `nginx-pre-reload` -> Warning: The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run `plugn trigger network-get-listeners APP` within any implementation of `nginx-pre-reload` in order to retrieve all application listeners. +> [!WARNING] +> The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run `plugn trigger network-get-listeners APP` within any implementation of `nginx-pre-reload` in order to retrieve all application listeners. - Description: Run before nginx reloads hosts - Invoked by: `dokku proxy:build-config` @@ -1410,7 +1415,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `post-build-pack` -> Warning: The pack plugin trigger apis are under development and may change +> [!WARNING] +> The pack plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using pack. @@ -1624,7 +1630,8 @@ haproxy-build-config "$APP" ### `post-release-builder` -> Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged. +> [!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 @@ -1676,7 +1683,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `pre-build-pack` -> Warning: The pack plugin trigger apis are under development and may change +> [!WARNING] +> The pack plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using pack. @@ -1832,7 +1840,8 @@ docker commit "${DOCKER_COMMIT_LABEL_ARGS[@]}" $CID $IMAGE >/dev/null ### `pre-release-pack` -> Warning: The pack plugin trigger apis are under development and may change +> [!WARNING] +> The pack plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack. @@ -1963,7 +1972,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `proxy-configure-ports` -> Warning: Deprecated, please use `ports-configure` instead +> [!WARNING] +> Deprecated, please use `ports-configure` instead - Description: Configures the port mapping - Invoked by: `internally triggered by proxy plugins` @@ -2192,7 +2202,8 @@ mail -s "$APP containers on $HOSTNAME failed to retire" ops@dokku.me ### `scheduler-app-status` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Fetch the status of an app @@ -2211,7 +2222,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-deploy` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when an app is deployed @@ -2230,7 +2242,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3"; ### `scheduler-detect` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to check which scheduler is in use for an app @@ -2249,7 +2262,8 @@ APP="$1" ### `scheduler-enter` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to enter a running container for a given app @@ -2268,7 +2282,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="$@" ### `scheduler-inspect` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run inspect commands for all containers for a given app @@ -2287,7 +2302,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-logs` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when retrieving container logs @@ -2306,7 +2322,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; PROCESS_TYPE="$3"; TAIL="$4"; PRETTY_PRINT="$5"; ### `scheduler-logs-failed` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when retrieving failed container logs @@ -2325,7 +2342,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-pre-restore` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run commands before an app is restored @@ -2344,7 +2362,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-post-delete` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when an app is deleted @@ -2363,7 +2382,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3"; ### `scheduler-post-run` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands after a `dokku run` invocation is called @@ -2382,7 +2402,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER_ID="$3"; ### `scheduler-register-retired` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows scheduling retiring a local container and any related images @@ -2402,7 +2423,8 @@ CONTAINER_ID="$2"; ### `scheduler-retire` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when containers should be force retired from the system @@ -2421,7 +2443,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ### `scheduler-run` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when a command is executed for your app @@ -2440,7 +2463,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="${@:3}"; ### `scheduler-run-list` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Lists all run containers for a given app @@ -2459,7 +2483,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; FORMAT="$3"; ### `scheduler-run-logs` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when retrieving one-off container logs @@ -2478,7 +2503,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER="$3"; TAIL="$4"; PRETTY_PRINT="$5"; NU ### `scheduler-stop` -> Warning: The scheduler plugin trigger apis are under development and may change +> [!WARNING] +> The scheduler plugin trigger apis are under development and may change > between minor releases until the 1.0 release. - Description: Allows you to run scheduler commands when a tag is destroyed diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md index bd3f7f8ab..0645869dd 100644 --- a/docs/getting-started/troubleshooting.md +++ b/docs/getting-started/troubleshooting.md @@ -1,5 +1,6 @@ # Troubleshooting +> [!IMPORTANT] > New as of 0.17.0 ``` diff --git a/docs/networking/dns.md b/docs/networking/dns.md index 80c5975b2..d3977018a 100644 --- a/docs/networking/dns.md +++ b/docs/networking/dns.md @@ -1,6 +1,7 @@ # DNS Configuration -> Note: This is a work in progress. +> [!NOTE] +> This is a work in progress. ## DNS Versions diff --git a/docs/networking/network.md b/docs/networking/network.md index 30f898de4..abf3d1989 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -1,5 +1,6 @@ # Network Management +> [!IMPORTANT] > New as of 0.11.0, Enhanced in 0.20.0 ``` @@ -20,6 +21,7 @@ The Network plugin allows developers to abstract the concept of container networ ### Listing networks +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ You can easily list all available networks using the `network:list` command: @@ -51,6 +53,7 @@ test-network ### Creating a network +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ Docker networks can be created via the `network:create` command. Executing this command will create an attachable `bridge` network. This can be used to route requests between containers without going through any public network. @@ -67,6 +70,7 @@ Specifying other additional flags or other types of networks can be created dire ### Destroying a network +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ A Docker network without any associated containers may be destroyed via the `network:destroy` command. Docker will refuse to destroy networks that have containers attached. @@ -95,6 +99,7 @@ dokku --force network:destroy test-network ### Checking if a network exists +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the `network:exists` command: @@ -111,6 +116,7 @@ The `network:exists` command will return non-zero if the network does not exist, ### Checking network info +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ Network information can be retrieved via the `network:info` command. This is a slightly different version of the `docker network` command. @@ -155,6 +161,7 @@ Only a single `$IP:$PORT` combination can be routed to for a given app, and that ### Attaching an app to a network +> [!IMPORTANT] > New as of 0.20.0, Requires Docker 1.21+ Apps will default to being associated with the default `bridge` network or a network specified by the `initial-network` network property. Additionally, an app can be attached to `attachable` networks by changing the `attach-post-create` or `attach-post-deploy` network properties when using the [docker-local scheduler](/docs/deployment/schedulers/docker-local.md). A change in these values will require an app deploy or rebuild. @@ -206,7 +213,8 @@ dokku network:set --global initial-network #### Network Aliases -> Note: This feature is only available when an app has been attached to a network other than the default `bridge` network. +> [!NOTE] +> This feature is only available when an app has been attached to a network other than the default `bridge` network. When a container created for a deployment is being attached to a network - regardless of which network property was used - a network alias of the pattern `APP.PROC_TYPE` will be added to all containers. This can be used to load-balance requests between containers. For an application named `node-js-app` with a process type of web, the network alias - or resolvable DNS record within the network - will be: @@ -292,7 +300,8 @@ Whatever the reason, the semantics of the two network hooks are important and ar - Use case: When another container on the network is already running and needed by this container. - Example: A key-value store exposing itself to all your apps may be on the `initial-network`. -> Warning: If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed. +> [!WARNING] +> If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed. ### Rebuilding network settings diff --git a/docs/networking/port-management.md b/docs/networking/port-management.md index 927f97f8a..5368889a9 100644 --- a/docs/networking/port-management.md +++ b/docs/networking/port-management.md @@ -1,5 +1,6 @@ # Port Management +> [!IMPORTANT] > New as of 0.31.0, replaces the previous `proxy:ports*` commands ``` @@ -12,7 +13,8 @@ ports:set :: [:: Warning: Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable. +> [!WARNING] +> Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable. > > Users should also avoid setting the `PORT` environment variable. Dokku will use port mappings to set this value. Overriding this manually may cause issues in application routing. @@ -20,7 +22,8 @@ You can now configure `host -> container` port mappings with the `ports:*` comma By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container. -> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below. +> [!NOTE] +> This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below. ### Port Scheme @@ -138,7 +141,8 @@ dokku ports:remove node-js-app http:80 ## Port management by Deployment Method -> Warning: If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment. +> [!WARNING] +> If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment. ### Buildpacks diff --git a/docs/networking/proxies/caddy.md b/docs/networking/proxies/caddy.md index fa1e70112..fe2f6b9c7 100644 --- a/docs/networking/proxies/caddy.md +++ b/docs/networking/proxies/caddy.md @@ -1,5 +1,6 @@ # Caddy Proxy +> [!IMPORTANT] > New as of 0.28.0 Dokku provides integration with the [Caddy](https://caddyserver.com/) proxy service by utilizing the Docker label-based integration implemented by Caddy. @@ -19,7 +20,8 @@ Using the `caddy` plugin integration requires the `docker-compose-plugin` for Do ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy. The Caddy plugin has specific rules for routing requests: diff --git a/docs/networking/proxies/haproxy.md b/docs/networking/proxies/haproxy.md index 94d57faa7..eda8e27bd 100644 --- a/docs/networking/proxies/haproxy.md +++ b/docs/networking/proxies/haproxy.md @@ -1,5 +1,6 @@ # Haproxy Proxy +> [!IMPORTANT] > New as of 0.28.0 Dokku provides integration with the [Haproxy](http://www.haproxy.org) proxy service by utilizing the Docker label-based integration implemented by [EasyHaproxy](https://github.com/byjg/docker-easy-haproxy). @@ -19,7 +20,8 @@ Using the `haproxy` plugin integration requires the `docker-compose-plugin` for ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy. The Haproxy plugin has specific rules for routing requests: diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md index 7fb14c93e..540ae72fd 100644 --- a/docs/networking/proxies/nginx.md +++ b/docs/networking/proxies/nginx.md @@ -15,7 +15,8 @@ nginx:validate-config [] [--clean] # Validates and optionally cleans up in ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. ### Request Proxying @@ -23,10 +24,12 @@ By default, the `web` process is the only process proxied by the nginx proxy imp Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) to the different deployed (scaled) containers running the `web` proctype. This way, the host's resources can be fully leveraged for single-threaded applications (e.g. `dokku ps:scale node-js-app web=4` on a 4-core machine). -> Note: Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers. +> [!NOTE] +> Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers. ### Starting nginx +> [!IMPORTANT] > New as of 0.28.0 The nginx server can be started via `nginx:start`. @@ -37,6 +40,7 @@ dokku nginx:start ### Stopping nginx +> [!IMPORTANT] > New as of 0.28.0 The nginx server can be stopped via `nginx:stop`. @@ -47,9 +51,11 @@ dokku nginx:stop ### Binding to specific addresses +> [!IMPORTANT] > New as of 0.19.2 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. By default, nginx will listen to all interfaces (`[::]` for IPv6, `0.0.0.0` for IPv4) when proxying requests to applications. This may be changed using the `bind-address-ipv4` and `bind-address-ipv6` properties. This is useful in cases where the proxying should be internal to a network or if there are multiple network interfaces that should respond with different content. @@ -65,15 +71,18 @@ dokku nginx:set node-js-app bind-address-ipv4 dokku nginx:set node-js-app bind-address-ipv6 ``` -> Warning: Validation is not performed on either value. +> [!WARNING] +> Validation is not performed on either value. Users with apps that contain a custom `nginx.conf.sigil` file will need to modify the files to respect the new `NGINX_BIND_ADDRESS_IPV4` and `NGINX_BIND_ADDRESS_IPV6` variables. ### HSTS Header +> [!IMPORTANT] > New as of 0.20.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via `nginx:set`: @@ -93,7 +102,8 @@ Beware that if you enable the header and a subsequent deploy of your application #### Globally disabling the HSTS Header -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. HSTS Header can be disabled for all apps by setting the `hsts` property to false after passing the `--global` flag to `nginx:set`. @@ -145,7 +155,8 @@ dokku nginx:set node-js-app x-forwarded-ssl ### Checking access logs -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. You may check nginx access logs via the `nginx:access-logs` command. This assumes that app access logs are being stored in `/var/log/nginx/$APP-access.log`, as is the default in the generated `nginx.conf`. @@ -175,9 +186,11 @@ dokku nginx:error-logs node-js-app -t ### Changing log path +> [!IMPORTANT] > New as of 0.20.1 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. The path to where log files are stored can be changed by calling the `nginx:set` command with the following options: @@ -202,9 +215,11 @@ In all cases, the nginx config must be regenerated after setting the above value ### Changing log format +> [!IMPORTANT] > New as of 0.22.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. The format of the access log can be changed by calling the `nginx:set` command as follows: @@ -245,9 +260,11 @@ dokku proxy:build-config node-js-app ### Specifying a read timeout +> [!IMPORTANT] > New as of 0.21.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. When proxying requests to your applications, it may be useful to specify a proxy read timeout. This can be done via the `nginx:set` command as follows: @@ -267,9 +284,11 @@ In all cases, the nginx config must be regenerated after setting the above value ### Specifying a custom client_max_body_size +> [!IMPORTANT] > New as of 0.23.0 -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. Users can override the default `client_max_body_size` value - which limits file uploads - via `nginx:set`. Changing this value will only apply to every `server` stanza of the default `nginx.conf.sigil`; users of custom `nginx.conf.sigil` files must update their templates to support the new value. @@ -309,7 +328,8 @@ As app nginx configs are actually executed within a shared context, it is possib The `nginx:validate-config` command also takes an optional `--clean` flag. If specified, invalid nginx configs will be removed. -> Warning: Invalid app nginx config's will be removed _even if_ the config is valid in the global server context. +> [!WARNING] +> Invalid app nginx config's will be removed _even if_ the config is valid in the global server context. ```shell dokku nginx:validate-config --clean @@ -323,6 +343,7 @@ dokku nginx:validate-config node-js-app --clean ### Customizing the nginx configuration +> [!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 overriden 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. @@ -352,7 +373,8 @@ dokku nginx:set --global nginx-conf-sigil-path #### Disabling custom nginx config -> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. +> [!NOTE] +> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command. While enabled by default, using a custom nginx config can be disabled via `nginx:set`. This may be useful in cases where you do not want to allow users to override any higher-level customization of app nginx config. @@ -383,7 +405,8 @@ Unsetting this value is the same as enabling custom nginx config usage. Finally, each process type has it's network listeners - a list of IP:PORT pairs for the respective app containers - exposed via an `.DOKKU_APP_${PROCESS_TYPE}_LISTENERS` variable - the `PROCESS_TYPE` will be upper-cased with hyphens transformed into underscores. Users can use the new variables to expose non-web processes via the nginx proxy. -> Note: Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`. +> [!NOTE] +> Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`. #### Customizing via configuration files included by the default templates @@ -436,7 +459,8 @@ These are provided as an alternative to the generic Nginx error page, are shared By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website. -> Warning: some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands: +> [!WARNING] +> some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands: > > ``` > rm /etc/nginx/sites-enabled/default diff --git a/docs/networking/proxies/openresty.md b/docs/networking/proxies/openresty.md index 65299f462..6a790ab20 100644 --- a/docs/networking/proxies/openresty.md +++ b/docs/networking/proxies/openresty.md @@ -1,5 +1,6 @@ # OpenResty Proxy +> [!IMPORTANT] > New as of 0.31.0 Dokku can provide integration with the [OpenResty](https://openresty.org/) proxy service by utilizing the Docker label-based integration implemented by [openresty-docker-proxy](https://github.com/dokku/openresty-docker-proxy). @@ -19,7 +20,8 @@ Using the `openresty` plugin integration requires the `docker-compose-plugin` fo ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty. The OpenResty plugin has specific rules for routing requests: diff --git a/docs/networking/proxies/traefik.md b/docs/networking/proxies/traefik.md index ceff53c77..bf89e9398 100644 --- a/docs/networking/proxies/traefik.md +++ b/docs/networking/proxies/traefik.md @@ -1,5 +1,6 @@ # Traefik Proxy +> [!IMPORTANT] > New as of 0.28.0 Dokku provides integration with the [Traefik](https://traefik.io/) proxy service by utilizing the Docker label-based integration implemented by Traefik. @@ -19,7 +20,8 @@ Using the `traefik` plugin integration requires the `docker-compose-plugin` for ## Usage -> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik. +> [!WARNING] +> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik. The Traefik plugin has specific rules for routing requests: @@ -154,7 +156,8 @@ Traefik exposes an API and Dashboard, which Dokku disables by default for securi #### Enabling the api -> Warning: Users enabling the dashboard should also enable api basic auth. +> [!WARNING] +> Users enabling the dashboard should also enable api basic auth. By default, the api is disabled. To enable, set the `api` property with the `--global` flag: @@ -166,7 +169,8 @@ After enabling, the Traefik container will need to be restarted. #### Enabling the dashboard -> Warning: Users enabling the dashboard should also enable api basic auth. +> [!WARNING] +> Users enabling the dashboard should also enable api basic auth. By default, the dashboard is disabled. To enable, set the `dashboard` property with the `--global` flag: diff --git a/docs/networking/proxy-management.md b/docs/networking/proxy-management.md index a07066541..49f58890b 100644 --- a/docs/networking/proxy-management.md +++ b/docs/networking/proxy-management.md @@ -1,5 +1,6 @@ # Proxy Management +> [!IMPORTANT] > New as of 0.5.0, Enhanced in 0.6.0 ``` @@ -43,6 +44,7 @@ dokku proxy:build-config --all --parallel -1 ### Clearing the generated proxy config +> [!IMPORTANT] > New as of 0.27.0 Generated proxy configurations can also be cleared using the `proxy:clear-config` command. @@ -61,6 +63,7 @@ Clearing a proxy configuration has different effects depending on the proxy plug ### Displaying proxy reports for an app +> [!IMPORTANT] > New as of 0.8.1 You can get a report about the app's proxy status using the `proxy:report` command: diff --git a/docs/processes/entering-containers.md b/docs/processes/entering-containers.md index 5fdf90840..4d663155d 100644 --- a/docs/processes/entering-containers.md +++ b/docs/processes/entering-containers.md @@ -1,5 +1,6 @@ # Entering containers +> [!IMPORTANT] > New as of 0.4.0 ``` diff --git a/docs/processes/one-off-tasks.md b/docs/processes/one-off-tasks.md index 60e148db7..11419dc94 100644 --- a/docs/processes/one-off-tasks.md +++ b/docs/processes/one-off-tasks.md @@ -16,6 +16,7 @@ Sometimes it is necessary to run a one-off command under an app. Dokku makes it The `run` command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container. The container image will be the same container image as was used to start the currently deployed app. +> [!IMPORTANT] > New as of 0.25.0, this container will be removed after the process exits. ```shell @@ -51,6 +52,7 @@ dokku --label=com.example.test-label=value run node-js-app ls -lah #### Disabling TTY +> [!IMPORTANT] > New as of 0.25.0 One-off containers default to interactive mode where possible. To disable this behavior, specify the `--no-tty` flag: @@ -61,6 +63,7 @@ dokku run --no-tty node-js-app ls -lah ### Running a detached container +> [!IMPORTANT] > New as of 0.25.0 Finally, a container can be run in "detached" mode via the `run:detached` Dokku command. Running a process in detached mode will immediately return a `CONTAINER_ID`. Detached containers are run without a tty and are also removed at the end of process execution. @@ -101,6 +104,7 @@ The above command will show logs continually from the `node-js-app.run.1234` one ### Listing one-off containers +> [!IMPORTANT] > New as of 0.25.0 One-off containers for a given app can be listed via the `run:list` command: @@ -136,6 +140,7 @@ dokku run:list node-js-app --format json ### Stopping a one-off container +> [!IMPORTANT] > New as of 0.29.0 Run containers for an app can be stopped via the `run:stop` command. The output will be the container id. diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index 8485eb52d..839081734 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -1,5 +1,6 @@ # Process Management +> [!IMPORTANT] > New as of 0.3.14, Enhanced in 0.7.0 ``` @@ -18,6 +19,7 @@ ps:stop [--parallel count] [--all|] # Stop an app ### Inspecting app containers +> [!IMPORTANT] > New as of 0.13.0 A common administrative task to perform is calling `docker inspect` on the containers that are running for an app. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the `ps:inspect` command: @@ -109,7 +111,8 @@ web: 1 #### Procfile -> Note: Dokku supports the Procfile format as defined in [this document](https://github.com/dokku/procfile-util/blob/master/PROCFILE_FORMAT.md) under "Strict Mode" parsing rules. +> [!NOTE] +> Dokku supports the Procfile format as defined in [this document](https://github.com/dokku/procfile-util/blob/master/PROCFILE_FORMAT.md) under "Strict Mode" parsing rules. Apps can define processes to run by using a `Procfile`. A `Procfile` is a simple text file that can be used to specify multiple commands, each of which is subject to process scaling. In the case where the built image sets a default command to run - either through usage of `CMD` for Dockerfile-based builds, a default process for buildpack-based builds, or any other method for the builder in use - the `Procfile` will take precedence. @@ -277,6 +280,7 @@ dokku ps:start --all --parallel -1 ### Restart policies +> [!IMPORTANT] > New as of 0.7.0, Command Changed in 0.22.0 By default, Dokku will automatically restart containers that exit with a non-zero status up to 10 times via the [on-failure Docker restart policy](https://docs.docker.com/engine/reference/run/#restart-policies---restart). @@ -313,6 +317,7 @@ Dokku also runs `dokku-event-listener` in the background via the system's init s ### Displaying reports for an app +> [!IMPORTANT] > New as of 0.12.0 You can get a report about the deployed apps using the `ps:report` command: diff --git a/docs/processes/scheduled-cron-tasks.md b/docs/processes/scheduled-cron-tasks.md index 5dce920ac..1a4212407 100644 --- a/docs/processes/scheduled-cron-tasks.md +++ b/docs/processes/scheduled-cron-tasks.md @@ -1,5 +1,6 @@ # Scheduled Cron Tasks +> [!IMPORTANT] > New as of 0.23.0 ``` @@ -125,7 +126,8 @@ dokku cron:report node-js-app --cron-task-count ### Self Managed Cron -> Warning: Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary. +> [!WARNING] +> Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary. Some installations may require more fine-grained control over cron usage. The following are advanced instructions for configuring cron. From 4ff26e6e365f0ff469688aa9b1c7f46d553a79d4 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 19 Aug 2023 14:30:18 -0400 Subject: [PATCH 3/5] fix: exec command so as to respect init properly --- docs/_build/entrypoint | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/_build/entrypoint b/docs/_build/entrypoint index 891f76432..7e842fb30 100755 --- a/docs/_build/entrypoint +++ b/docs/_build/entrypoint @@ -23,17 +23,15 @@ main() { fi if [[ "$CMD" == "deps" ]]; then - pip freeze - return $? + exec pip freeze fi if [[ "$CMD" == "serve" ]]; then write-mkdocs - mkdocs serve -a 0.0.0.0:3487 - return $? + exec mkdocs serve -a 0.0.0.0:3487 fi - "$CMD" "${ARGS[@]}" + exec "$CMD" "${ARGS[@]}" } main "$@" From f780a8a6f86908d12fd76788509e8e4968b1fd64 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 19 Aug 2023 15:04:25 -0400 Subject: [PATCH 4/5] docs: fix shell output --- docs/networking/network.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/networking/network.md b/docs/networking/network.md index abf3d1989..f1c24bfba 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -79,7 +79,7 @@ A Docker network without any associated containers may be destroyed via the `net dokku network:destroy test-network ``` -```shell +``` ! WARNING: Potentially Destructive Action ! This command will destroy network test. ! To proceed, type "test" @@ -93,7 +93,7 @@ As the command is destructive, it will default to asking for confirmation before dokku --force network:destroy test-network ``` -```shell +``` -----> Destroying network test ``` @@ -353,7 +353,7 @@ CONTAINER ID IMAGE COMMAND CREATED As such, the container's IP address will be an internal IP, and thus it is only accessible on the host itself: -``` +```shell docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' node-js-app.web.1 ``` From 3306f29c11bc52ce3bd6938e9d641d0f64405c26 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 19 Aug 2023 15:43:31 -0400 Subject: [PATCH 5/5] docs: handle new github admonitions and cleanup write-mkdocs script --- contrib/write-mkdocs | 257 +++++++++++++++++++++++++++++++------------ 1 file changed, 184 insertions(+), 73 deletions(-) diff --git a/contrib/write-mkdocs b/contrib/write-mkdocs index 36f400ea3..67170e435 100644 --- a/contrib/write-mkdocs +++ b/contrib/write-mkdocs @@ -1,13 +1,19 @@ #!/usr/bin/env python -from bs4 import BeautifulSoup import os import pathlib import shutil import sys +from collections.abc import Callable + import yaml +from bs4 import BeautifulSoup -def get_nav_from_selector(soup, selector, docs_dir): + +def get_nav_from_selector(soup: BeautifulSoup, selector: str, docs_dir: str): + """ + Generates navigation from template file + """ navigation = [] header_name = "" for anchor in soup.select(selector): @@ -49,44 +55,50 @@ def get_nav_from_selector(soup, selector, docs_dir): children = os.listdir(docs_dir + "/" + child_dir) children = [child_dir + c for c in children] children.sort() - children.insert( - 0, "getting-started/advanced-installation.md") + children.insert(0, "getting-started/advanced-installation.md") if os.path.exists(docs_dir + "/" + filename): children.insert(0, filename) else: - children.insert( - 0, "getting-started/installation/index.md") - nav[header_name].append({ - "Getting Started with Dokku": children, - }) + children.insert(0, "getting-started/installation/index.md") + nav[header_name].append( + { + "Getting Started with Dokku": children, + } + ) continue - elif filename == "getting-started/upgrading.md": + + if filename == "getting-started/upgrading.md": child_dir = "appendices/" children = os.listdir(docs_dir + "/" + child_dir) - children.sort(key=lambda x: list( - map(int, x.split("-")[0].split('.'))), - reverse=True) + children.sort( + key=lambda x: list(map(int, x.split("-")[0].split("."))), + reverse=True, + ) children = [child_dir + c for c in children] if os.path.exists(docs_dir + "/" + filename): children.insert(0, filename) else: - children.insert( - 0, "getting-started/upgrading/index.md") - nav[header_name].append({ - "Upgrading": children, - }) + children.insert(0, "getting-started/upgrading/index.md") + nav[header_name].append( + { + "Upgrading": children, + } + ) continue - else: - nav[header_name].append(filename) + + nav[header_name].append(filename) return navigation -def generate_nav(src, dest): +def generate_nav(src: str, dest: str) -> None: + """ + Writes out navigation information to the mkdocs yaml file + """ navigation = [] repo_dir = pathlib.Path(__file__).parent.parent.resolve() docs_dir = str(repo_dir) + "/docs" - with open(docs_dir + "/template.html") as response: + with open(docs_dir + "/template.html", encoding="utf-8") as response: soup = BeautifulSoup(response, "html.parser") selectors = [ ".container .row .list-group a", @@ -101,21 +113,26 @@ def generate_nav(src, dest): print("No navigation found") sys.exit(1) - with open(src) as f: - data = yaml.unsafe_load(f) + with open(src, encoding="utf-8") as handler: + data = yaml.unsafe_load(handler) data["nav"] = [ {"Docs": navigation}, {"Pro": "https://pro.dokku.com/docs/getting-started/"}, {"Blog": "https://dokku.com/blog/"}, {"Tutorials": "https://dokku.com/tutorials/"}, - {"Purchase Dokku Pro": "https://dokku.dpdcart.com/cart/add?product_id=217344&method_id=236878"}, + { + "Purchase Dokku Pro": "https://dokku.dpdcart.com/cart/add?product_id=217344&method_id=236878" + }, ] - with open(dest, mode="wt", encoding="utf-8") as f: - yaml.dump(data, f) + with open(dest, mode="wt", encoding="utf-8") as handler: + yaml.dump(data, handler) -def modify_content_noop(lines, _): +def modify_content_noop(lines: list[str], _) -> tuple[list[str], bool]: + """ + Simply returns the lines as is + """ modified = False updated_lines = [] for line in lines: @@ -123,11 +140,14 @@ def modify_content_noop(lines, _): return updated_lines, modified -def modify_content_links(lines, filename): +def modify_content_links(lines: list[str], filename: str) -> tuple[list[str], bool]: + """ + Modifies links to be relative instead of absolute + """ filename = filename.replace("/usr/src/source/docs/", "") parts = filename.split("/") parts.pop() - replacement = "](" + '/'.join([".." for _ in parts]) + "/" + replacement = "](" + "/".join([".." for _ in parts]) + "/" modified = False updated_lines = [] for line in lines: @@ -139,7 +159,10 @@ def modify_content_links(lines, filename): return updated_lines, modified -def modify_content_stripspace(lines, _): +def modify_content_stripspace(lines: list[str], _) -> tuple[list[str], bool]: + """ + Removes trailing whitespace from each line + """ modified = False updated_lines = [] for line in lines: @@ -148,7 +171,10 @@ def modify_content_stripspace(lines, _): return updated_lines, modified -def modify_content_inject_newlines(lines, _): +def modify_content_inject_newlines(lines: list[str], _) -> tuple[list[str], bool]: + """ + Ensures every line has a trailing newline character + """ modified = False updated_lines = [] for line in lines: @@ -156,47 +182,117 @@ def modify_content_inject_newlines(lines, _): return updated_lines, modified -def is_info(line): +def is_github_new(line: str, next_line: str | None) -> bool: + """ + Checks if a given line is a github "new as of" admonition + """ + if not next_line: + return False + + return line.startswith("> [!IMPORTANT]") and "new as of" in next_line.lower() + + +def is_github_note(line: str) -> bool: + """ + Checks if a given line is a github "note" admonition + """ + return line.startswith("> [!NOTE]") + + +def is_github_warning(line: str) -> bool: + """ + Checks if a given line is a github "warning" admonition + """ + return line.startswith("> [!WARNING]") + + +def is_info(line: str) -> bool: + """ + Checks if a given line is an "info" admonition + """ return line.startswith("> ") -def is_new(line): +def is_new(line: str) -> bool: + """ + Checks if a given line is a "new as of" admonition + """ return line.startswith("> ") and "new as of" in line.lower() -def is_note(line): +def is_note(line: str) -> bool: + """ + Checks if a given line is a "note" admonition + """ return line.startswith("> Note:") -def is_warning(line): +def is_warning(line: str) -> bool: + """ + Checks if a given line is a "warning" admonition + """ return line.startswith("> Warning:") -def modify_content_admonition(lines, _): +def modify_content_admonition(lines: list[str], _) -> tuple[list[str], bool]: + """ + Applies adminition info to each line in the output + """ modified = False updated_lines = [] admonition_lines = [] is_admonition = False - for line in lines: - if is_info(line) or is_new(line) or is_note(line) or is_warning(line): - if is_new(line): - line = line.replace("> ", "!!! tip \"New\"\n\n ") - line = line.replace("New as of", "Introduced in") - line = line.replace("new as of", "introduced in") - if is_note(line): - line = line.replace( - "> Note: ", "!!! note \"Note\"\n\n ") - elif is_warning(line): - line = line.replace( - "> Warning: ", "!!! warning \"Warning\"\n\n ") - elif is_info(line): - if not is_admonition: - line = line.replace("> ", "!!! info \"Info\"\n\n ") - elif line in [">", "> "]: - line = "" - else: - line = " " + line.removeprefix("> ") + replace_new_in_next_line = False + for index, line in enumerate(lines): + next_line: str | None = None + if index + 1 < len(lines): + next_line = lines[index + 1] + if replace_new_in_next_line: + line = line.replace("New as of", "Introduced in") + line = line.replace("new as of", "introduced in") + replace_new_in_next_line = False + + if is_github_new(line, next_line): + line = line.replace("> [!IMPORTANT]", '!!! tip "New"') + is_admonition = True + admonition_lines.append(line) + admonition_lines.append("") + replace_new_in_next_line = True + elif is_github_note(line): + line = line.replace("> [!NOTE]", '!!! note "Note"') + is_admonition = True + admonition_lines.append(line) + admonition_lines.append("") + elif is_github_warning(line): + line = line.replace("> [!WARNING]", '!!! warning "Warning"') + is_admonition = True + admonition_lines.append(line) + admonition_lines.append("") + elif is_new(line): + print("is_new") + line = line.replace("> ", '!!! tip "New"\n\n ') + line = line.replace("New as of", "Introduced in") + line = line.replace("new as of", "introduced in") + is_admonition = True + admonition_lines.append(line) + elif is_note(line): + print("is_note") + line = line.replace("> Note: ", '!!! note "Note"\n\n ') + is_admonition = True + admonition_lines.append(line) + elif is_warning(line): + print("is_warning") + line = line.replace("> Warning: ", '!!! warning "Warning"\n\n ') + is_admonition = True + admonition_lines.append(line) + elif is_info(line): + if not is_admonition: + line = line.replace("> ", '!!! info "Info"\n\n ') + elif line in [">", "> "]: + line = "" + else: + line = " " + line.removeprefix("> ") is_admonition = True admonition_lines.append(line) elif is_admonition and line in [">", "> "]: @@ -208,6 +304,7 @@ def modify_content_admonition(lines, _): elif line == "": is_admonition = False if len(admonition_lines) > 0: + modified = True updated_lines.extend(admonition_lines) admonition_lines = [] updated_lines.append("") @@ -216,11 +313,17 @@ def modify_content_admonition(lines, _): return updated_lines, modified -def is_shell_codeblock_start(line): +def is_shell_codeblock_start(line: str) -> bool: + """ + Checks to see if a line starts a codeblock + """ return line == "```shell" -def modify_content_terminal_example(lines, _): +def modify_content_terminal_example(lines: list[str], _) -> tuple[list[str], bool]: + """ + Modifies content so that terminal output is shown appropriately + """ modified = False updated_lines = [] command_block = [] @@ -246,20 +349,20 @@ def modify_content_terminal_example(lines, _): if previous_block == "": updated_lines.append(line) continue - elif previous_block == "command_block": + if previous_block == "command_block": example_block.append(line) if in_example_block: previous_block = "" in_example_block = False - updated_lines.append("=== \"Shell\"") + updated_lines.append('=== "Shell"') updated_lines.append("") for command_line in command_block: updated_lines.append(f" {command_line}") command_block = [] updated_lines.append("") - updated_lines.append("=== \"Output\"") + updated_lines.append('=== "Output"') updated_lines.append("") for example_line in example_block: updated_lines.append(f" {example_line}") @@ -278,7 +381,7 @@ def modify_content_terminal_example(lines, _): command_block = [] previous_block = "" continue - elif next_line_must_be == "": + if next_line_must_be == "": if line == "": next_line_must_be = None continue @@ -292,6 +395,9 @@ def modify_content_terminal_example(lines, _): def update_markdown(src): + """ + Updates all markdown files to be mkdocs compatible + """ markdown_files = [] allowed_extensions = [".md"] for subdir, _, files in os.walk(src): @@ -301,7 +407,7 @@ def update_markdown(src): if ext in allowed_extensions: markdown_files.append(file_path) - modifiers = [ + modifiers: list[Callable[[list[str], str], tuple[list[str], bool]]] = [ modify_content_noop, modify_content_links, modify_content_stripspace, @@ -311,27 +417,32 @@ def update_markdown(src): ] for file in markdown_files: - modified = False + is_modified = False lines = [] - with open(file, 'r') as f: - lines = f.readlines() + with open(file, "r", encoding="utf-8") as handler: + lines = handler.readlines() for modifier in modifiers: - lines, m = modifier(lines, file) - if m: - modified = True + lines, modified = modifier(lines, file) + if modified: + is_modified = True - if modified: - with open(file, 'w') as fp: - fp.writelines(lines) + if is_modified: + with open(file, "w", encoding="utf-8") as handler: + handler.writelines(lines) def main(): + """ + Main command that performs doc manipulation + """ print("----> Copying mkdocs.yml") print(" Generating navigation") generate_nav("/usr/src/source/mkdocs.yml", "/usr/src/app/mkdocs.yml") print("----> Copying docs folder") - update_markdown("/usr/src/source/docs",) + update_markdown( + "/usr/src/source/docs", + ) if os.path.exists("/usr/src/app/docs"): print(" Removing old docs folder")