|
1 | | -#Buildpack Modes |
| 1 | +# Buildpack Modes |
| 2 | +The Java Buildpack has three execution modes as described in the blog post, ['Packaged and Offline Buildpacks'][l]. |
2 | 3 |
|
3 | | -The Java Buildpack has three execution modes: |
| 4 | +* **Easy Mode:** Uses the repository at `https://download.run.pivotal.io`. This does not require any cloning or downloading unless you want to modify the Cloud Foundry provided buildpack. This is the default, and what we recommend to anyone who asks. |
| 5 | +* **Expert Mode:** Refers to a repository hosted at a different location, possibly on an internal network. The [structure of the repository[r] is defined as an HTTP-accessible collection of files. The repository root must contain an `index.yml` file that is a mapping of concrete versions to absolute URIs. This repository can be created manually or [creating a replica](#replicating-the-repository-optional) for the repository at `https://download.run.pivotal.io`. This is what we would recommend to any customer that didn’t want to access the Internet. It’s easy to keep applications secure and up-to-date, but requires the expertise to run a web-server and keep it up to date. |
| 6 | +* **Offline Mode:** Uses only the packaged internal cache. This is what we recommend if you wanted a single, self-contained artifact. The downside is having to package and keep all your dependencies up to date. |
4 | 7 |
|
5 | | -* Easy Mode: Uses the repository at [http://download.run.pivotal.io][1]. This does not require any cloning or downloading unless you want to modify the Cloud Foundry provided buildpack. This is the default, and what we recommend anyone to use. |
6 | | -* Expert Mode: Uses a full or partial replica of the repository at [http://download.run.pivotal.io][1] hosted at a different location, possibly a local intranet. The replica must at least include the `index.yml` files that point to the actual artifacts. This is what we recommend to anyone that does not want to access the Internet. It’s easy to keep applications secure and up-to-date, but requires the expertise to run a web-server and keep it in sync with [http://download.run.pivotal.io][1]. |
7 | | -* Offline Mode: Uses only the packaged internal cache. This is what we recommend if you wanted a single, self-contained artifact. The downside is having to package and keep all your dependencies up to date. |
8 | 8 |
|
9 | | -##Replicating the Repository (Optional) |
| 9 | +## Easy Mode |
| 10 | +The "Easy Mode" buildpack is included in all Cloud Foundry distributions and used by default. To configure the buildpack, refer to [Configuration and Extension][c]. |
10 | 11 |
|
11 | | -In order to use Expert Mode you will need to make a replica of the repository at [http://download.run.pivotal.io][1], then fork the `java-buildpack` and update the [configuration][4] of `default_repository_root` to point to your copy of the repository. |
| 12 | +You can also download specific versions of the buildpack to use with the `create-buildpack`, and `update-buildpack` Cloud Foundry CLI commands. To find these, navigate to the [Java Buildpack Releases page][v] and download one of the following: |
12 | 13 |
|
13 | | -To make a replica of the repository at [http://download.run.pivotal.io][1], first download the artifacts and `index.yml` files as described [here][3], make them available at a suitable locations on a web server. All the artifacts and `index.yml` files may be downloaded using the [`replicate`][5] script from the [Java Buildpack Dependency Builder][3] repository. |
| 14 | + * `java-buildpack-v<VERSION>.zip` |
| 15 | + * Source Code (zip) |
14 | 16 |
|
15 | | -To use the script, issue the following commands from the root directory of a clone of the [Java Buildpack Dependency Builder][3] repository: |
| 17 | +To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-v<VERSION>.zip` command. For more details refer to the [Cloud Foundry buildpack documentation][b]. |
16 | 18 |
|
17 | | -```bash |
18 | | -bundle install |
19 | | -bundle exec bin/replicate [--base-uri <BASE-URI> | --host-name <HOST-NAME>] --output <OUTPUT> |
20 | | -``` |
21 | 19 |
|
22 | | -| Option | Description | |
23 | | -| ------ | ----------- | |
24 | | -| `-b`, `--base-uri <BASE-URI>` | A URI to replace `https://download.run.pivotal.io` with, in `index.yml` files. This value should be the network location that the repository is replicated to (e.g. `https://internal-repository:8000/dependencies`). Either this option or `--host-name`, but not both, **must** be specified. |
25 | | -| `-h`, `--host-name <HOST-NAME>` | A host name to replace `download.run.pivotal.io` with, in `index.yml` files. This value should be the network host that the repository is replicated to (e.g. `internal-repository`). Either this option or `--base-uri`, but not both, **must** be specified. |
26 | | -| `-o`, `--output <OUTPUT>` | A filesystem location to replicate the repository to. This option **must** be specified. |
| 20 | +## Expert Mode |
| 21 | +The "Expert Mode" buildpack is a minor fork of the default Java Buildpack. For details on configuring the buildpack, refer to [Configuration and Extension][c]. To configure the buildpack to point at an alternate repository, modify the [`config/repository.yml`][y] file to use a different `default_repository_root`. |
27 | 22 |
|
28 | | -##Creating an Offline Buildpack |
| 23 | +```yaml |
| 24 | +# Repository configuration |
| 25 | +--- |
| 26 | +default_repository_root: https://<ALTERNATE_HOST> |
| 27 | +``` |
29 | 28 |
|
30 | | -You can download a packaged build of the buildpack from either [master-Tarball][7], [master-zip][8], [release-offline][9] [release-tarball][10], [release-zip][11]. An offline buildpack can also be built from a local clone of [this][6] Git repository run `bundle exec rake clean package OFFLINE=true` to create a zipped copy of the buildpack. Then use the `cf create-buildpack` and `cf update-buildpack` commands to add or update your new buildpack to a Cloud Foundry instance. |
| 29 | +Once the buildpack has been modified, it needs to be packaged and uploaded to the Cloud Foundry instance. In order to package the modified buildpack, refer to [Building Packages][p]. To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-v<VERSION>.zip` command. For more details refer to the [Cloud Foundry buildpack documentation][b]. |
31 | 30 |
|
| 31 | +### Replicating the Repository _(Optional)_ |
| 32 | +The easiest way to create a fully populated internal repository is to replicate the one found at `https://download.run.pivotal.io`. The [Java Buildpack Dependency Builder][d] contains a `replicate` script that automates this process. To use the script, issue the following commands from the root directory of a clone of this repository: |
| 33 | + |
| 34 | +```bash |
| 35 | +$ bundle install |
| 36 | +$ bundle exec bin/replicate [--base-uri <BASE-URI> | --host-name <HOST-NAME>] --output <OUTPUT> |
32 | 37 | ``` |
33 | | -NAME: |
34 | | - create-buildpack - Create a buildpack |
35 | 38 |
|
36 | | -USAGE: |
37 | | - cf create-buildpack BUILDPACK PATH POSITION [--enable|--disable] |
| 39 | +For details on using the `replicate script` refer to [Replicating Repository][e]. |
38 | 40 |
|
39 | | -TIP: |
40 | | - Path should be a zip file, a url to a zip file, or a local directory. Position is an integer, sets priority, and is sorted from lowest to highest. |
41 | 41 |
|
42 | | -OPTIONS: |
43 | | - --enable Enable the buildpack |
44 | | - --disable Disable the buildpack |
45 | | -``` |
| 42 | +## Offline Mode |
| 43 | +The "Offline Mode" buildpack is a self-contained packaging of either the "Easy Mode" or "Expert Mode" buildpacks. |
| 44 | + |
| 45 | +You can download specific versions of the "Offline Mode" buildpack to use with the `create-buildpack` and `update-buildpack` Cloud Foundry CLI commands. To find these, navigate to the [Java Buildpack Releases page][v] and download one of the `java-buildpack-offline-v<VERSION>.zip` file. In order to package a modified "Offline Mode" buildpack, refer to [Building Packages][p]. To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-offline-v<VERSION>.zip` command. For more details refer to the [Cloud Foundry buildpack documentation][b]. |
46 | 46 |
|
47 | | -``` |
48 | | -NAME: |
49 | | - update-buildpack - Update a buildpack |
50 | | -
|
51 | | -USAGE: |
52 | | - cf update-buildpack BUILDPACK [-p PATH] [-i POSITION] [--enable|--disable] [--lock|--unlock] |
53 | | -
|
54 | | -OPTIONS: |
55 | | - -i Buildpack position among other buildpacks |
56 | | - -p Path to directory or zip file |
57 | | - --enable Enable the buildpack |
58 | | - --disable Disable the buildpack |
59 | | - --lock Lock the buildpack |
60 | | - --unlock Unlock the buildpack |
61 | | -``` |
62 | 47 |
|
63 | | -To gain a better understanding of the different ways the Java Buildpack can be used you can read this blog post, ['Packaged and Offline Buildpacks'][2]. |
64 | | - |
65 | | -[1]: http://download.run.pivotal.io/ |
66 | | -[2]: http://blog.cloudfoundry.org/2014/04/03/packaged-and-offline-buildpacks/ |
67 | | -[3]: https://github.com/cloudfoundry/java-buildpack-dependency-builder |
68 | | -[4]: https://github.com/cloudfoundry/java-buildpack/blob/master/config/repository.yml |
69 | | -[5]: https://github.com/cloudfoundry/java-buildpack-dependency-builder/blob/master/bin/replicate |
70 | | -[6]: https://github.com/cloudfoundry/java-buildpack |
71 | | -[7]: https://github.com/cloudfoundry/java-buildpack/archive/master.tar.gz |
72 | | -[8]: https://github.com/cloudfoundry/java-buildpack/archive/master.zip |
73 | | -[9]: https://github.com/cloudfoundry/java-buildpack/releases/download/v2.4/java-buildpack-offline-v2.4.zip |
74 | | -[10]: https://github.com/cloudfoundry/java-buildpack/archive/v2.4.tar.gz |
75 | | -[11]: https://github.com/cloudfoundry/java-buildpack/archive/v2.4.zip |
| 48 | +[b]: http://docs.pivotal.io/pivotalcf/adminguide/buildpacks.html |
| 49 | +[c]: ../README.md#configuration-and-extension |
| 50 | +[d]: https://github.com/cloudfoundry/java-buildpack-dependency-builder |
| 51 | +[e]: https://github.com/cloudfoundry/java-buildpack-dependency-builder#replicating-repository |
| 52 | +[l]: http://blog.cloudfoundry.org/2014/04/03/packaged-and-offline-buildpacks/ |
| 53 | +[p]: ../README.md#building-packages |
| 54 | +[r]: https://github.com/cloudfoundry/java-buildpack/blob/master/docs/extending-repositories.md#repository-structure |
| 55 | +[v]: https://github.com/cloudfoundry/java-buildpack/releases |
| 56 | +[y]: ../config/repository.yml |
0 commit comments