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

feat: implement builder plugin

Browse Source 
This plugin will allow users to override the builder used for their application, enabling users to use custom builders if desired.
This commit is contained in:
Jose Diaz-Gonzalez
2021-02-28 17:25:03 -05:00
parent 1ec71cd509
commit 8c34cfe64e
21 changed files with 566 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/deployment/methods/cloud-native-buildpacks.md
View File

@@ -1,64 +0,0 @@
# Cloud Native Buildpacks (Experimental)
> New as of 0.22.0
```
buildpacks:set-property [--global|<app>] <key> <value> # Set or clear a buildpacks property for an app
```
Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the [herokuish buildpacks documentation](/docs/deployment/methods/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.
## Usage
To use this builder instead of either `Dockerfile` or `herokuish`, you must set the `DOKKU_CNB_EXPERIMENTAL` environment variable for your app to `1`.
```shell
dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1
```
The `pack` cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on [this page](https://buildpacks.io/docs/tools/pack/).
Builds will proceed with the `pack` cli for the app from then on.
## Caveats
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.
- 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.
- 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.
- `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.
### Customizing the Buildpack stack builder
> New as of 0.23.0
The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/buildpacks`. 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.
```shell
dokku buildpacks:set-property node-js-app stack paketobuildpacks/build:base-cnb
```
The specified stack builder can also be unset by omitting the name of the stack builder when calling `buildpacks:set-property`.
```shell
dokku buildpacks:set-property node-js-app stack
```
A change in the stack builder value will execute the `post-stack-set` trigger.
Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_CNB_STACK` environment variable (`heroku/buildpacks` by default).
```shell
# set globally
dokku buildpacks:set-property --global stack paketobuildpacks/build:base-cnb
# unset globally
dokku buildpacks:set-property --global stack
```

123
docs/deployment/methods/dockerfiles.md
View File

@@ -1,123 +0,0 @@
# Dockerfile Deployment
> New as of 0.3.15
While Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use Docker's native `Dockerfile` system to define a container.
> Dockerfile support is considered a *power user* feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
To use a Dockerfile for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers *except* in the following two cases:
- The application has a `BUILDPACK_URL` environment variable set via the `dokku config:set` command or in a committed `.env` file. In this case, Dokku will use your specified buildpack.
- The application has a `.buildpacks` file in the root of the repository. In this case, Dokku will use your specified buildpack(s).
## Switching from buildpack deployments
If an application was previously deployed via buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
```shell
dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP
```
## Build-time configuration variables
For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available only during runtime.
For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](docs/advanced-usage/docker-options.md):
```shell
dokku docker-options:add node-js-app build '--build-arg NODE_ENV=production'
```
The location of the `Dockerfile` may also be specified. If the location is changed, the repository **must also** have a `Dockerfile` in the root directory in order to trigger a dockerfile-based deploy.
```shell
dokku docker-options:add node-js-app build '--file Dockerfile.dokku'
```
Once set, the Dockerfile usage would be as follows:
```Dockerfile
FROM ubuntu:18.04
# set the argument default
ARG NODE_ENV=production
# use the argument
RUN echo $NODE_ENV
```
You may also set the argument as an environment variable
```Dockerfile
FROM ubuntu:18.04
# set the argument default
ARG NODE_ENV=production
# assign it to an environment variable
# we can wrap the variable in brackets
ENV NODE_ENV ${NODE_ENV}
# or omit them completely
# use the argument
RUN echo $NODE_ENV
```
## Building images with Docker Buildkit
If your Dockerfile is using Docker engine's [buildkit](https://docs.docker.com/develop/develop-images/build_enhancements/) (not to be confused with buildpacks), then the `DOCKER_BUILDKIT=1` environment variable needs to be set. One way to do this is to edit `/etc/environment` on your dokku host and reboot your instance. Note, for complete build log output, you should also set `BUILDKIT_PROGRESS=plain` in the same file.
## Customizing the run command
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
```Dockerfile
ENTRYPOINT ["node"]
```
You can do:
```shell
dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD="--harmony server.js"
```
To tell Docker what to run.
Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`.
### Procfiles and multiple processes
> New as of 0.5.0
You can also customize the run command using a `Procfile`, much like you would on Heroku or
with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
When you deploy your app, a Docker image will be built. The `Procfile` will be extracted from the image
(it must be in the folder defined in your `Dockerfile` as `WORKDIR` or `/app`) and the commands
in it will be passed to `docker run` to start your process(es). Here's an example `Procfile`:
```Procfile
web: bin/run-prod.sh
worker: bin/run-worker.sh
```
And `Dockerfile`:
```Dockerfile
FROM ubuntu:18.04
WORKDIR /app
COPY . ./
CMD ["bin/run-dev.sh"]
```
When you deploy this app the `web` process will automatically be scaled to 1 and your Docker container
will be started basically using the command `docker run bin/run-prod.sh`. If you want to also run
a worker container for this app, you can run `dokku ps:scale worker=1` and a new container will be
started by running `docker run bin/run-worker.sh` (the actual `docker run` commands are a bit more
complex, but this is the basic idea). If you use an `ENTRYPOINT` in your `Dockerfile`, the lines
in your `Procfile` will be passed as arguments to the `ENTRYPOINT` script instead of being executed.
## Exposed ports
See the [port management documentation](/docs/networking/port-management.md) for more information on how Dokku exposes ports for applications and how you can configure these for your app.

265
docs/deployment/methods/herokuish-buildpacks.md
View File

@@ -1,265 +0,0 @@
# Herokuish Buildpack Deployment
> Subcommands new as of 0.15.0
```
buildpacks:add [--index 1] <app> <buildpack> # Add new app buildpack while inserting into list of buildpacks if necessary
buildpacks:clear <app> # Clear all buildpacks set on the app
buildpacks:list <app> # List all buildpacks for an app
buildpacks:remove <app> <buildpack> # Remove a buildpack set on the app
buildpacks:report [<app>] [<flag>] # Displays a buildpack report for one or more apps
buildpacks:set [--index 1] <app> <buildpack> # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified
buildpacks:set-property [--global|<app>] <key> <value> # Set or clear a buildpacks 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.
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.
- 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 page will cover usage of the `buildpacks` plugin.
## Usage
### Listing Buildpacks in Use
The `buildpacks:list` command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.
```shell
# running for an app with no buildpacks specified
dokku buildpacks:list node-js-app
```
```
-----> test buildpack urls
```
```shell
# running for an app with two buildpacks specified
dokku buildpacks:list node-js-app
```
```
-----> test buildpack urls
https://github.com/heroku/heroku-buildpack-python.git
https://github.com/heroku/heroku-buildpack-nodejs.git
```
### Adding custom buildpacks
> Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
To add a custom buildpack, use the `buildpacks:add` command:
```shell
dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
```
When no buildpacks are currently specified, the specified buildpack will be the only one executed for detection and compilation.
Multiple buildpacks may be specified by using the `buildpacks:add` command multiple times.
```shell
dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
```
Buildpacks are executed in order, may be inserted at a specified index via the `--index` flag. This flag is specified starting at a 1-index value.
```shell
# will add the golang buildpack at the second position, bumping all proceeding ones by 1 position
dokku buildpacks:add --index 2 node-js-app https://github.com/heroku/heroku-buildpack-golang.git
```
### Overwriting a buildpack position
In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the `buildpacks:set` command can be used to overwrite a buildpack at a given position.
```shell
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
```
By default, this will overwrite the _first_ buildpack specified. To specify an index, the `--index` flag may be used. This flag is specified starting at a 1-index value, and defaults to `1`.
```shell
# the following are equivalent commands
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
dokku buildpacks:set --index 1 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
```
If the index specified is larger than the number of buildpacks currently configured, the buildpack will be appended to the end of the list.
```shell
dokku buildpacks:set --index 99 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
```
### Removing a buildpack
> At least one of a buildpack or index must be specified
A single buildpack can be removed by name via the `buildpacks:remove` command.
```shell
dokku buildpacks:remove node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
```
Buildpacks can also be removed by index via the `--index` flag. This flag is specified starting at a 1-index value.
```shell
dokku buildpacks:remove node-js-app --index 1
```
### Clearing all buildpacks
> This does not affect automatically detected buildpacks, nor does it impact any specified `BUILDPACK_URL` environment variable.
The `buildpacks:clear` command can be used to clear all configured buildpacks for a specified app.
```shell
dokku buildpacks:clear node-js-app
```
### Customizing the Buildpack stack builder
> 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.
```shell
dokku buildpacks:set-property node-js-app stack gliderlabs/herokuish:latest
```
The specified stack builder can also be unset by omitting the name of the stack builder when calling `buildpacks:set-property`.
```shell
dokku buildpacks:set-property node-js-app stack
```
A change in the stack builder value will execute the `post-stack-set` trigger.
Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_IMAGE` environment variable (`gliderlabs/herokuish:latest` by default).
```shell
# set globally
dokku buildpacks:set-property --global stack gliderlabs/herokuish:latest
# unset globally
dokku buildpacks:set-property --global stack
```
### Displaying buildpack reports for an app
You can get a report about the app's buildpacks status using the `buildpacks:report` command:
```shell
dokku buildpacks:report
```
```
=====> node-js-app buildpacks information
Buildpacks computed stack: gliderlabs/herokuish:v0.5.23-20
Buildpacks global stack: gliderlabs/herokuish:latest
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git
Buildpacks stack: gliderlabs/herokuish:v0.5.23-20
=====> python-sample buildpacks information
Buildpacks computed stack: gliderlabs/herokuish:v0.5.23-20
Buildpacks global stack: gliderlabs/herokuish:latest
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
Buildpacks stack:
=====> ruby-sample buildpacks information
Buildpacks computed stack: gliderlabs/herokuish:v0.5.23-20
Buildpacks global stack: gliderlabs/herokuish:latest
Buildpacks list:
Buildpacks stack:
```
You can run the command for a specific app also.
```shell
dokku buildpacks:report node-js-app
```
```
=====> node-js-app buildpacks information
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git
```
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku buildpacks:report node-js-app --buildpacks-list
```
## Errata
### Switching from Dockerfile deployments
If an application was previously deployed via Dockerfile, the following commands should be run before a buildpack deploy will succeed:
```shell
dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP
```
### Using a specific buildpack version
> Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.
By default, Dokku uses the [gliderlabs/herokuish](https://github.com/gliderlabs/herokuish/) project, which pins all of it's vendored buildpacks. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified *without* a Git commit SHA like so:
```shell
# using the latest nodejs buildpack
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs
```
This will use the latest commit on the `master` branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form `REPOSITORY_URL#COMMIT_SHA`, where `COMMIT_SHA` is any tree-ish git object - usually a git tag.
```shell
# using v87 of the nodejs buildpack
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87
```
### Specifying commands via Procfile
While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/docs/processes/process-management.md) for more details around scaling individual processes.
A Procfile is a file named `Procfile`. It should be named `Procfile` exactly, and not anything else. For example, `Procfile.txt` is not valid. The file should be a simple text file.
The file must be placed in the root directory of your application. It will not function if placed in a subdirectory.
If the file exists, it should not be empty, as doing so may result in a failed deploy.
The syntax for declaring a `Procfile` is as follows. Note that the format is one process type per line, with no duplicate process types.
```
<process type>: <command>
```
If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types:
```Procfile
worker: env QUEUE=* bundle exec rake resque:work
importantworker: env QUEUE=important bundle exec rake resque:work
```
The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/docs/processes/process-management.md) for more details around scaling individual processes.
### `curl` build timeouts
Certain buildpacks may time out in retrieving dependencies via `curl`. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a `curl` command.
If you see output similar this when deploying , you may need to override the `curl` timeouts to increase the length of time allotted to those tasks. You can do so via the `config` plugin:
```shell
dokku config:set --global CURL_TIMEOUT=1200
dokku config:set --global CURL_CONNECT_TIMEOUT=180
```
### Clearing buildpack cache
See the [repository management documentation](/docs/advanced-usage/repository-management.md#clearing-app-cache) for more information on how to clear buildpack build cache for an application.