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

feat: implement buildpacks plugin

Browse Source 
This will allow users to specify buildpacks outside of a git repository.

Note that this does not override any specified `BUILDPACK_URL`.

Closes #3256
This commit is contained in:
Jose Diaz-Gonzalez
2019-01-21 19:41:49 -05:00
parent a56ae22614
commit 887c1d4254
31 changed files with 2066 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
docs/deployment/methods/buildpacks.md
View File

@@ -1,13 +1,165 @@
# 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
```
> 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:
- Use `dokku config:set` to set the `BUILDPACK_URL` environment variable.
- Add `BUILDPACK_URL` to a committed `.env` file in the root of your repository.
- See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
- 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.
## Switching from Dockerfile deployments
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 node-js-app --index 2 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
```
### Displaying buildpack reports about 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 list: https://github.com/heroku/heroku-buildpack-nodejs.git
=====> python-sample buildpacks information
Buildpacks list: https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
=====> ruby-sample buildpacks information
Buildpacks list:
```
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:
@@ -15,54 +167,25 @@ If an application was previously deployed via Dockerfile, the following commands
dokku config:unset --no-restart node-js-app DOKKU_DOCKERFILE_CMD DOKKU_DOCKERFILE_ENTRYPOINT DOKKU_PROXY_PORT_MAP
```
## Specifying a custom buildpack
In certain cases you may want to specify a custom buildpack. While Dokku uses Herokuish to support all the [official Heroku buildpacks](https://github.com/gliderlabs/herokuish#buildpacks), it is possible that the buildpack detection does not work well for your application. As well, you may wish to use a custom buildpack to handle specific application logic.
To use a specific buildpack, you can run the following Dokku command:
```shell
# replace REPOSITORY_URL with your buildpack's url
dokku config:set node-js-app BUILDPACK_URL=REPOSITORY_URL
# example: using a specific ruby buildpack version
dokku config:set node-js-app BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-ruby.git#v142
```
Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
## Using multiple buildpacks
You can only set a single buildpack using the `BUILDPACK_URL`, though there may be times when you wish to use multiple buildpacks. To do so, simply create a `.buildpacks` file in the base of your repository. This file should list all the buildpacks, one-per-line. For instance, if you wish to use both the `nodejs` and `ruby` buildpacks, your `.buildpacks` file should contain the following:
```shell
https://github.com/heroku/heroku-buildpack-nodejs.git#v87
https://github.com/heroku/heroku-buildpack-ruby.git#v142
```
### 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.
You may also choose to set just a single buildpack in this file, though that is up to you.
Please check the documentation for your particular buildpack(s) as you may need to include configuration files (such as a Procfile) in your project root.
## Using a specific buildpack version
As Dokku pins all buildpacks via Herokuish releases, there may be occasions where a local buildpack version is out of date. If you wish to use a more recent version of the buildpack, you may use any of the above methods to specify a buildpack *without* the Git SHA attached like so:
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 config:set node-js-app BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs
```
You may also wish to use a *specific* version of a buildpack, which is also simple
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 config:set node-js-app BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs#v87
dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87
```
## Specifying commands via Procfile
### 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/deployment/process-management.md) for more details around scaling individual processes.
@@ -87,17 +210,18 @@ 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/deployment/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.
### `curl` build timeouts
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:
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
### Clearing buildpack cache
See the [repository management documentation](/docs/advanced-usage/repository-management.md#clearing-app-cache).