diff --git a/docs/advanced-usage/backup-recovery.md b/docs/advanced-usage/backup-recovery.md index 44f4ac3f4..32ea6952a 100644 --- a/docs/advanced-usage/backup-recovery.md +++ b/docs/advanced-usage/backup-recovery.md @@ -81,7 +81,6 @@ The plugin directory is contained at the `/var/lib/dokku/plugins` directory. Cor Note that restoring a plugin will not trigger any `install` or `dependencies` triggers. You will need to run these manually. See the [plugin management documentation](/docs/advanced-usage/plugin-management.md#installing-a-plugin) for more information on how to trigger these two hooks. - ### Volumes and Static Assets Dokku doesn't enforce a [300mb](https://devcenter.heroku.com/articles/slug-compiler#slug-size) limit on apps, but it's best practice to keep binary assets outside of git. Since containers are considered volatile in Dokku, external stores like s3 or storage mounts should be used for non-volatile items like user uploads. The Dokku storage core plugin can be used to mount local directories / volumes inside the docker container. diff --git a/docs/community/plugins.md b/docs/community/plugins.md index 4c3ebacef..aa3301d05 100644 --- a/docs/community/plugins.md +++ b/docs/community/plugins.md @@ -167,7 +167,7 @@ The following plugins have been removed as their functionality is now in Dokku C | Plugin | Author | In Dokku Since | | ------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------- | | [App User](https://github.com/michaelshobbs/dokku-app-user) | [michaelshobbs][] | v0.7.1 (herokuish 0.3.18) | -| [Custom Domains](https://github.com/neam/dokku-custom-domains) | [motin][] | v0.3.10 (domains plugin) | +| [Custom Domains](https://github.com/neam/dokku-custom-domains) | [neam][] | v0.3.10 (domains plugin) | | [Debug](https://github.com/josegonzalez/dokku-debug) | [josegonzalez][] | v0.3.9 (trace command) | | [Docker Options](https://github.com/dyson/dokku-docker-options) | [dyson][] | v0.3.17 (docker-options plugin) | | [Dokku Name](https://github.com/alex-sherwin/dokku-name) | [alex-sherwin][] | v0.4.2 (named containers plugin) | @@ -194,7 +194,6 @@ The following plugins have been removed as their functionality is now in Dokku C | [Supply env vars to buildpacks](https://github.com/cameron-martin/dokku-build-env)2 | [cameron-martin][] | v0.3.9 (build-env plugin) | | [user-env-compile](https://github.com/motin/dokku-user-env-compile)2 | [motin][] | v0.3.9 (build-env plugin) | | [user-env-compile](https://github.com/musicglue/dokku-user-env-compile)2 | [musicglue][] | v0.3.9 (build-env plugin) | -| [VHOSTS Custom Configuration](https://github.com/neam/dokku-nginx-vhosts-custom-configuration) | [motin][] | v0.3.10 (domains plugin) | | [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) @@ -284,14 +283,12 @@ The following plugins are no longer maintained by their developers. [mikexstudios]: https://github.com/mikexstudios [mimischi]: https://github.com/mimischi [mixxorz]: https://github.com/mixxorz -[mlebkowski]: https://github.com/mlebkowski [motin]: https://github.com/motin [mrname]: https://github.com/mrname [musicglue]: https://github.com/musicglue [neam]: https://github.com/neam [nickcharlton]: https://github.com/nickcharlton [nickstenning]: https://github.com/nickstenning -[nornagon]: https://github.com/nornagon [ohardy]: https://github.com/ohardy [pauldub]: https://github.com/pauldub [pnegahdar]: https://github.com/pnegahdar @@ -302,7 +299,6 @@ The following plugins are no longer maintained by their developers. [scottatron]: https://github.com/scottatron [sehrope]: https://github.com/sehrope [sekjun9878]: https://github.com/sekjun9878 -[sseemayer]: https://github.com/sseemayer [statianzo]: https://github.com/statianzo [stuartpb]: https://github.com/stuartpb [thrashr888]: https://github.com/thrashr888 diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 45305f554..70d5b6227 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -14,11 +14,11 @@ 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). +> 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). Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys. -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. +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. diff --git a/docs/configuration/nginx.md b/docs/configuration/nginx.md index 67f939729..497f86b5d 100644 --- a/docs/configuration/nginx.md +++ b/docs/configuration/nginx.md @@ -255,7 +255,7 @@ Dokku uses a templating library by the name of [sigil](https://github.com/glider - If `WORKDIR` is specified, add the file to the `WORKDIR` specified in the last Dockerfile stage (example: `WORKDIR /app` and `ADD nginx.conf.sigil /app`). - If no `WORKDIR` is specified, add the file to the root (`/`) of the docker image (example: `ADD nginx.conf.sigil /`). -> When using a custom `nginx.conf.sigil` file, depending upon your application configuration, you *may* be exposing the file externally. As this file is extracted before the container is run, you can, safely delete it in a custom `entrypoint.sh` configured in a Dockerfile `ENTRYPOINT`. +> When using a custom `nginx.conf.sigil` file, depending upon your application configuration, you _may_ be exposing the file externally. As this file is extracted before the container is run, you can, safely delete it in a custom `entrypoint.sh` configured in a Dockerfile `ENTRYPOINT`. > The default template is available [here](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil), and can be used as a guide for your own, custom `nginx.conf.sigil` file. Please refer to the appropriate template file version for your Dokku version. @@ -271,7 +271,6 @@ dokku nginx:set node-js-app disable-custom-config true Unsetting this value is the same as enabling custom nginx config usage. - #### Available template variables ``` @@ -311,17 +310,21 @@ service nginx reload The example above uses additional configuration files directly on the Dokku host. Unlike the `nginx.conf.sigil` file, these additional files will not be copied over from your application repo, and thus need to be placed in the `/home/dokku/node-js-app/nginx.conf.d/` directory manually. -For PHP Buildpack users, you will also need to provide a `Procfile` and an accompanying `nginx.conf` file to customize the nginx config *within* the container. The following are example contents for your `Procfile` +For PHP Buildpack users, you will also need to provide a `Procfile` and an accompanying `nginx.conf` file to customize the nginx config _within_ the container. The following are example contents for your `Procfile` - web: vendor/bin/heroku-php-nginx -C nginx.conf -i php.ini php/ +``` +web: vendor/bin/heroku-php-nginx -C nginx.conf -i php.ini php/ +``` Your `nginx.conf` file - not to be confused with Dokku's `nginx.conf.sigil` - would also need to be configured as shown in this example: - client_header_timeout 50s; - location / { - index index.php; - try_files $uri $uri/ /index.php$is_args$args; - } +``` +client_header_timeout 50s; +location / { + index index.php; + try_files $uri $uri/ /index.php$is_args$args; +} +``` Please adjust the `Procfile` and `nginx.conf` file as appropriate. diff --git a/docs/deployment/application-management.md b/docs/deployment/application-management.md index 39a6a92eb..66b96c5b6 100644 --- a/docs/deployment/application-management.md +++ b/docs/deployment/application-management.md @@ -191,7 +191,6 @@ dokku apps:clone --ignore-existing node-js-app io-js-app 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. - ```shell dokku apps:lock node-js-app ``` diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index c0353de88..ef52f71fc 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -92,7 +92,6 @@ RUN --mount=target=/var/lib/apt/lists,type=cache \ Mount cache targets may vary depending on the tool in use, and users are encouraged to investigate the directories that apply for their language and framework. - You would adjust the cache directory for whatever application cache you have, e.g. `/root/.pnpm-store/v3` for pnpm, `$HOME/.m2` for maven, or `/root/.cache` for golang. ### Customizing the run command diff --git a/docs/deployment/continuous-integration/github-actions.md b/docs/deployment/continuous-integration/github-actions.md index 147b3e3ff..cb3cd5640 100644 --- a/docs/deployment/continuous-integration/github-actions.md +++ b/docs/deployment/continuous-integration/github-actions.md @@ -27,5 +27,4 @@ jobs: ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }} ``` - For further usage documentation and other advanced examples, see the entry on the [GitHub Marketplace](https://github.com/marketplace/actions/dokku). diff --git a/docs/deployment/logs.md b/docs/deployment/logs.md index e8d69b443..50ba2bb76 100644 --- a/docs/deployment/logs.md +++ b/docs/deployment/logs.md @@ -172,6 +172,6 @@ Valid values for `SINK_TYPE` include all log vector log sinks, while `SINK_OPTIO - `int`: form: `key=int` - `[string]`: form: `key[]=string` - `[int]`: form: `key[]=int` -- `table`: form: `option[key]=value +- `table`: form: `option[key]=value` Please read the [sink documentation](https://vector.dev/docs/reference/sinks/) for your sink of choice to configure the sink as desired. diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index 0b0f68109..23a5ac4ff 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -114,4 +114,3 @@ Use `visudo /etc/sudoers.d/dokku-users`, or `visudo /etc/sudoers` to add the fol ``` %dokku ALL=(ALL:ALL) NOPASSWD:SETENV: /usr/bin/dokku ``` - diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index d00013828..2fbadae2a 100644 --- a/docs/development/plugin-triggers.md +++ b/docs/development/plugin-triggers.md @@ -326,7 +326,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `core-post-deploy` -> To avoid issues with community plugins, this plugin trigger should be used *only* for core plugins. Please avoid using this trigger in your own plugins. +> To avoid issues with community plugins, this plugin trigger should be used _only_ for core plugins. Please avoid using this trigger in your own plugins. - Description: Allows running of commands after an app's processes have been scaled up, but before old containers are torn down. Dokku core currently uses this to switch traffic on nginx. - Invoked by: `dokku deploy` @@ -743,9 +743,7 @@ 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` @@ -1177,7 +1175,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: @@ -1281,7 +1279,7 @@ sudo service haproxy reload ### `post-extract` -- Description: Allows you to modify the contents of an app *after* it has been extracted from git/tarball but *before* the image source type is detected. +- Description: Allows you to modify the contents of an app _after_ it has been extracted from git/tarball but _before_ the image source type is detected. - Invoked by: `dokku tar:in`, `dokku tar:from` and the `receive-app` plugin trigger - Arguments: `$APP` `$TMP_WORK_DIR` `$REV` - Example: @@ -1571,7 +1569,6 @@ DOCKER_COMMIT_LABEL_ARGS=("--change" "LABEL org.label-schema.schema-version=1.0" 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 @@ -2224,10 +2221,10 @@ APP="$1"; IMAGE_TAG="$2" ### `uninstall` - - Description: Used to cleanup after itself. - - Invoked by: `dokku plugin:uninstall` - - Arguments: `$PLUGIN` - - Example: +- Description: Used to cleanup after itself. +- Invoked by: `dokku plugin:uninstall` +- Arguments: `$PLUGIN` +- Example: ```shell #!/usr/bin/env bash @@ -2261,7 +2258,7 @@ sudo BUILD_STACK=true make install ### `user-auth` -This is a special plugin trigger that is executed on *every* command run. As Dokku sometimes internally invokes the `dokku` command, special care should be taken to properly handle internal command redirects. +This is a special plugin trigger that is executed on _every_ command run. As Dokku sometimes internally invokes the `dokku` command, special care should be taken to properly handle internal command redirects. Note that the trigger should exit as follows: @@ -2270,7 +2267,7 @@ Note that the trigger should exit as follows: The `SSH_USER` is the original ssh user. If you are running remote commands, this user will typically be `dokku`, and as such should not be trusted when checking permissions. If you are connected via ssh as a different user who then invokes `dokku`, the value of this variable will be that user's name (`root`, `myuser`, etc.). -The `SSH_NAME` is the `NAME` variable set via the `sshcommand acl-add` command. If you have set a user via the `dokku-installer`, this value will be set to `admin`. For installs via debian package, this value *may* be `default`. For reference, the following command can be run as the root user to specify a specific `NAME` for a given ssh key: +The `SSH_NAME` is the `NAME` variable set via the `sshcommand acl-add` command. If you have set a user via the `dokku-installer`, this value will be set to `admin`. For installs via debian package, this value _may_ be `default`. For reference, the following command can be run as the root user to specify a specific `NAME` for a given ssh key: ```shell sshcommand acl-add dokku NAME < $PATH_TO_SSH_KEY diff --git a/docs/getting-started/install/rpm.md b/docs/getting-started/install/rpm.md index be839c396..52c12106b 100644 --- a/docs/getting-started/install/rpm.md +++ b/docs/getting-started/install/rpm.md @@ -2,7 +2,7 @@ > New as of 0.8.0 *(experimental)* ->**Warning:** Web installer is not available on CentOS. You will need to configure [SSH keys](/docs/deployment/user-management.md#adding-ssh-keys) and [virtual hosts](/docs/configuration/domains.md#customizing-hostnames) using dokku command line interface. +> **Warning:** Web installer is not available on CentOS. You will need to configure [SSH keys](/docs/deployment/user-management.md#adding-ssh-keys) and [virtual hosts](/docs/configuration/domains.md#customizing-hostnames) using dokku command line interface. Dokku defaults to being installed via RPM package on CentOS 7. While certain hosts may require extra work to get running, you may optionally wish to automate the installation of Dokku without the use of our `bootstrap.sh` Bash script. The following are the steps run by said script: diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md index e413ffb00..ebecbc6de 100644 --- a/docs/getting-started/troubleshooting.md +++ b/docs/getting-started/troubleshooting.md @@ -33,9 +33,7 @@ dokku trace:off ## Common Problems -__Symptom:__ I deployed my app but I am getting the default nginx page. - -__Solution:__ +### 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: @@ -66,27 +64,22 @@ Save the file and try stopping nginx and starting it again: ## * Starting nginx nginx [ OK ] ``` -*** +### I want to deploy my app, but while pushing I get the following error -__Symptom:__ I want to deploy my app, but while pushing I get the following error. +The following error may be emitted from a deploy: - ! [remote rejected] master -> master (pre-receive hook declined) - -__Solution:__ +``` +! [remote rejected] master -> master (pre-receive hook declined) +``` 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. - -*** - -__Symptom:__ I get the aforementioned error in the build phase (after turning on Dokku tracing). +### I get the aforementioned error in the build phase (after turning on Dokku tracing) Most errors that happen in this phase are due to transient network issues (either locally or remotely) buildpack bugs. -__Solution (Less solution, more helpful troubleshooting steps):__ - Find the failed phase's container image (`077581956a92` in this example). ```shell @@ -113,26 +106,26 @@ resolvconf -u Please see https://github.com/dokku/dokku/issues/841 and https://github.com/dokku/dokku/issues/649. -*** +### After adding an SSH key, I am told I cannot read from the remote repository on push -__Symptom:__ After adding an SSH key, I still see the following error on deploy: +``` +Connection closed by port 22 +fatal: Could not read from remote repository. - Connection closed by port 22 - fatal: Could not read from remote repository. - - Please make sure you have the correct access rights - and the repository exists. +Please make sure you have the correct access rights +and the repository exists. +``` Certain systems may have access to the `dokku` user via SSH disabled. Please check that the `dokku` user is allowed access to the system in the file `/etc/security/access.conf`. As Dokku does not manage this file, please consult your Operating System's documentation for more information. -*** +### I want to deploy my app but I am getting asked for the password of the Git user -__Symptom:__ I want to deploy my app but I am getting asked for the password of the Git user and the error message. +Sometimes the following error message may be shown on push - fatal: 'NAME' does not appear to be a git repository - fatal: Could not read from remote repository. - -__Solution:__ +``` +fatal: 'NAME' does not appear to be a git repository +fatal: Could not read from remote repository. +``` You get asked for a password because your SSH secret key can't be found. This may happen if the private key corresponding to the public key you added with `sshcommand acl-add` is not located in the default location `~/.ssh/id_rsa`. @@ -145,11 +138,7 @@ Host DOKKU_HOSTNAME Also see [issue #116](https://github.com/dokku/dokku/issues/116). -*** - -__Symptom:__ I successfully deployed my application with no deployment errors and receiving **Bad Gateway** when attempting to access the application. - -__Solution:__ +### 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. @@ -161,11 +150,7 @@ var port = process.env.PORT || 3000 Please see https://github.com/dokku/dokku/issues/282. -*** - -__Symptom:__ Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file`. - -__Solution:__ +### Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file`. If you see output similar this when deploying: @@ -189,11 +174,7 @@ Please see 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`. -*** - -__Symptom:__ Build fails with `Killed` message. - -__Solution:__ +### 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. @@ -207,11 +188,7 @@ sudo sysctl -w vm.swappiness=10 echo vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf ``` -*** - -__Symptom:__ I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application. - -__Solution:__ +### 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: @@ -225,11 +202,7 @@ If the previous script returned `Status: active` and a list of ports, UFW is ena sudo ufw disable ``` -*** - -__Symptom:__ I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection. - -__Solution:__ +### 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. @@ -237,11 +210,7 @@ In Rails at least, if your `application.rb` or `environmnents/production.rb` inc If this solves the issue temporarily, longer term you should consider [configuring SSL](/docs/configuration/ssl.md). -*** - -__Symptom:__ My application deploys properly, but won't load in browser "connection refused" - -__Solution:__ +### My application deploys properly, but won't load in browser "connection refused" This could be a result of a bad proxy configuration (`http:5000:5000` may be incorrect). Run `dokku proxy:report myapp` to check if your app has the correct proxy configuration. It should show something like the following. diff --git a/docs/networking/network.md b/docs/networking/network.md index 01869cece..5014873d0 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -250,7 +250,6 @@ 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. ### Rebuilding network settings