github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: use github admonitions

Browse Source 
These still need to be properly parsed.
This commit is contained in:
Jose Diaz-Gonzalez
2023-08-19 14:24:12 -04:00
parent 5dd78e2b86
commit d61d91cf87
47 changed files with 277 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/deployment/application-deployment.md
View File

@@ -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 ~/<your private key>`.
> [!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 ~/<your private key>`.
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

14
docs/deployment/application-management.md
View File

@@ -1,5 +1,6 @@
# Application Management
> [!IMPORTANT]
> New as of 0.3.1
```
@@ -19,6 +20,7 @@ apps:unlock <app> # 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:

4
docs/deployment/builders/builder-management.md
View File

@@ -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.

6
docs/deployment/builders/cloud-native-buildpacks.md
View File

@@ -1,5 +1,6 @@
# Cloud Native Buildpacks
> [!IMPORTANT]
> New as of 0.22.0
```
@@ -13,7 +14,8 @@ buildpacks:set-property [--global|<app>] <key> <value> # 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.

3
docs/deployment/builders/dockerfiles.md
View File

@@ -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.

7
docs/deployment/builders/herokuish-buildpacks.md
View File

@@ -1,5 +1,6 @@
# Herokuish Buildpacks
> [!IMPORTANT]
> Subcommands new as of 0.15.0
```
@@ -17,7 +18,8 @@ builder-herokuish:report [<app>] [<flag>] # Displays a builder-herokuish repor
builder-herokuish:set <app> <key> (<value>) # 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:

1
docs/deployment/builders/lambda.md
View File

@@ -1,5 +1,6 @@
# Lambda Builder
> [!IMPORTANT]
> New as of 0.28.0
```

1
docs/deployment/builders/null.md
View File

@@ -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.

7
docs/deployment/logs.md
View File

@@ -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.

13
docs/deployment/methods/git.md
View File

@@ -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:

4
docs/deployment/schedulers/docker-local.md
View File

@@ -1,5 +1,6 @@
# Docker Local Scheduler
> [!IMPORTANT]
> Subcommands new as of 0.12.12
```
@@ -7,6 +8,7 @@ scheduler-docker-local:report [<app>] [<flag>] # Displays a schedul
scheduler-docker-local:set <app> <key> (<value>) # 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.

3
docs/deployment/schedulers/kubernetes.md
View File

@@ -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.

6
docs/deployment/schedulers/nomad.md
View File

@@ -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.

1
docs/deployment/schedulers/null.md
View File

@@ -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.

1
docs/deployment/schedulers/scheduler-management.md
View File

@@ -1,5 +1,6 @@
# Scheduler Management
> [!IMPORTANT]
> New as of 0.26.0
```

3
docs/deployment/user-management.md
View File

@@ -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`.

6
docs/deployment/zero-downtime-deploys.md
View File

@@ -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.