Skip to content

Commit b4dbf3b

Browse files
MalaxMalax
committed
Improve README structure and documentation
1 parent 0ef59b4 commit b4dbf3b

1 file changed

Lines changed: 40 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,64 @@
1-
Heroku buildpack for Java [![CI](https://github.com/heroku/heroku-buildpack-java/actions/workflows/ci.yml/badge.svg)](https://github.com/heroku/heroku-buildpack-java/actions/workflows/ci.yml)
2-
=========================
3-
41
![java](https://cloud.githubusercontent.com/assets/871315/20325947/f3544014-ab43-11e6-9c51-8240ce161939.png)
52

6-
This is the official [Heroku buildpack](http://devcenter.heroku.com/articles/buildpack) for Java apps.
7-
It uses Maven 3.9.4 to build your application and OpenJDK 8 to run it. However, the JDK version can be configured as described below.
8-
9-
## How it works
10-
11-
The buildpack will detect your app as Java if it has a `pom.xml` file, or one of the other POM formats supports by the [Maven Polyglot](https://github.com/takari/polyglot-maven) plugin, in its root directory. It will use Maven to execute the build defined by your `pom.xml` and download your dependencies. The `.m2` folder (local maven repository) will be cached between builds for faster dependency resolution. However neither the `mvn` executable nor the `.m2` folder will be available in your slug at runtime.
12-
13-
## Documentation
14-
15-
For more information about using Java and buildpacks on Heroku, see these Dev Center articles:
16-
17-
* [Heroku Java Support](https://devcenter.heroku.com/articles/java-support)
18-
* [Introduction to Heroku for Java Developers](https://devcenter.heroku.com/articles/intro-for-java-developers)
19-
* [Deploying Tomcat-based Java Web Applications with Webapp Runner](https://devcenter.heroku.com/articles/java-webapp-runner)
20-
* [Deploy a Java Web Application that launches with Jetty Runner](https://devcenter.heroku.com/articles/deploy-a-java-web-application-that-launches-with-jetty-runner)
21-
* [Using a Custom Maven Settings File](https://devcenter.heroku.com/articles/using-a-custom-maven-settings-xml)
22-
* [Using Grunt with Java and Maven to Automate JavaScript Tasks](https://devcenter.heroku.com/articles/using-grunt-with-java-and-maven-to-automate-javascript-tasks)
23-
24-
## Examples
25-
26-
* [Tomcat Webapp-Runner Example](https://github.com/kissaten/webapp-runner-minimal)
27-
* [Spring Boot Example](https://github.com/kissaten/spring-boot-heroku-demo)
28-
29-
## Configuration
30-
31-
### Choose a JDK
3+
# Heroku Buildpack: Java (Maven) [![CI](https://github.com/heroku/heroku-buildpack-java/actions/workflows/ci.yml/badge.svg)](https://github.com/heroku/heroku-buildpack-java/actions/workflows/ci.yml)
324

33-
Create a `system.properties` file in the root of your project directory and set `java.runtime.version=1.8`.
5+
This is the official [Heroku buildpack](https://devcenter.heroku.com/articles/buildpacks) for apps that use [Maven](https://maven.apache.org/) as their build tool. It's primarily used to build [Java](https://www.java.com/) applications, but it can also build applications written in other JVM languages.
346

35-
Example:
7+
If you're using a different JVM build tool, use the appropriate buildpack:
8+
* [Gradle buildpack](https://github.com/heroku/heroku-buildpack-gradle) for [Gradle](https://gradle.org/) projects
9+
* [Scala buildpack](https://github.com/heroku/heroku-buildpack-scala) for [sbt](https://www.scala-sbt.org/) projects
10+
* [Clojure buildpack](https://github.com/heroku/heroku-buildpack-clojure) for [Leiningen](https://leiningen.org/) projects
3611

37-
$ ls
38-
Procfile pom.xml src
12+
## Table of Contents
3913

40-
$ echo "java.runtime.version=1.8" > system.properties
14+
- [Supported Maven Versions](#supported-maven-versions)
15+
- [Getting Started](#getting-started)
16+
- [Application Requirements](#application-requirements)
17+
- [Configuration](#configuration)
18+
- [OpenJDK Version](#openjdk-version)
19+
- [Maven Version](#maven-version)
20+
- [Buildpack Configuration](#buildpack-configuration)
21+
- [Documentation](#documentation)
4122

42-
$ git add system.properties && git commit -m "Java 8"
23+
## Supported Maven Versions
4324

44-
$ git push heroku main
45-
...
46-
-----> Java app detected
47-
-----> Installing OpenJDK 1.8... done
48-
-----> Installing Maven 3.3.3... done
49-
...
25+
This buildpack officially supports Maven `3.x`. Maven `4.x` support will be added after its release.
5026

51-
### Choose a Maven Version
27+
## Getting Started
5228

53-
You can define a specific version of Maven for Heroku to use by adding the
54-
[Maven Wrapper](https://github.com/takari/maven-wrapper) to your project. When
55-
this buildpack detects the presence of a `mvnw` script and a `.mvn` directory,
56-
it will run the Maven Wrapper instead of the default `mvn` command.
29+
See the [Getting Started with Java on Heroku](https://devcenter.heroku.com/articles/getting-started-with-java) tutorial.
5730

58-
If you need to override this, the `system.properties` file also allows for a `maven.version` entry
59-
(regardless of whether you specify a `java.runtime.version` entry). For example:
31+
## Application Requirements
6032

61-
```
62-
java.runtime.version=1.8
63-
maven.version=3.3.9
64-
```
33+
Your app requires a `pom.xml` file, or one of the other POM formats supported by the [Maven Polyglot](https://github.com/takari/polyglot-maven) plugin, in the root directory.
6534

66-
### Customize Maven
67-
68-
There are three config variables that can be used to customize the Maven execution:
69-
70-
+ `MAVEN_CUSTOM_GOALS`: set to `clean dependency:list install` by default
71-
+ `MAVEN_CUSTOM_OPTS`: set to `-DskipTests` by default
72-
+ `MAVEN_JAVA_OPTS`: set to `-Xmx1024m` by default
73-
74-
These variables can be set like this:
75-
76-
```sh-session
77-
$ heroku config:set MAVEN_CUSTOM_GOALS="clean package"
78-
$ heroku config:set MAVEN_CUSTOM_OPTS="--update-snapshots -DskipTests=true"
79-
$ heroku config:set MAVEN_JAVA_OPTS="-Xss2g"
80-
```
81-
82-
Other options are available for [defining a custom `settings.xml` file](https://devcenter.heroku.com/articles/using-a-custom-maven-settings-xml).
83-
84-
## Development
85-
86-
To make changes to this buildpack, fork it on Github. Push up changes to your fork, then create a new Heroku app to test it, or configure an existing app to use your buildpack:
87-
88-
```
89-
# Create a new Heroku app that uses your buildpack
90-
heroku create --buildpack <your-github-url>
91-
92-
# Configure an existing Heroku app to use your buildpack
93-
heroku buildpacks:set <your-github-url>
35+
## Configuration
9436

95-
# You can also use a git branch!
96-
heroku buildpacks:set <your-github-url>#your-branch
97-
```
37+
### OpenJDK Version
9838

99-
For example if you want to have Maven available to use at runtime in your application, you can copy it from the cache directory to the build directory by adding the following lines to the compile script:
39+
Specify an OpenJDK version by creating a `system.properties` file in the root of your project directory and setting the `java.runtime.version` property. See the [Java Support article](https://devcenter.heroku.com/articles/java-support#supported-java-versions) for available versions and configuration instructions.
10040

101-
for DIR in ".m2" ".maven" ; do
102-
cp -r $CACHE_DIR/$DIR $BUILD_DIR/$DIR
103-
done
41+
### Maven Version
10442

105-
This will copy the local Maven repo and Maven binaries into your slug.
43+
Specify a Maven version by adding the [Maven Wrapper](https://maven.apache.org/tools/wrapper/) to your project. When this buildpack detects the presence of a `mvnw` script and a `.mvn` directory, it will run the Maven Wrapper instead of the default `mvn` command.
10644

107-
Commit and push the changes to your buildpack to your GitHub fork, then push your sample app to Heroku to test. Once the push succeeds you should be able to run:
45+
Alternatively, you can set the `maven.version` property in `system.properties`, though using the Maven Wrapper is the recommended approach.
10846

109-
$ heroku run bash
47+
### Buildpack Configuration
11048

111-
and then:
49+
Configure the buildpack by setting environment variables:
11250

113-
$ ls -al
51+
| Environment Variable | Description | Default |
52+
|---------------------|-------------|---------|
53+
| `MAVEN_CUSTOM_GOALS` | Maven goals to execute | `clean dependency:list install` |
54+
| `MAVEN_CUSTOM_OPTS` | Maven command-line options | `-DskipTests` |
55+
| `MAVEN_JAVA_OPTS` | JVM options for Maven execution | (none) |
56+
| `MAVEN_SETTINGS_PATH` | Path to a custom `settings.xml` file | (none) |
57+
| `MAVEN_SETTINGS_URL` | URL from which to download a custom `settings.xml` file | (none) |
58+
| `MAVEN_HEROKU_CI_GOAL` | Maven goal for Heroku CI test runs | `test` |
11459

115-
and you'll see the `.m2` and `.maven` directories are now present in your slug.
60+
For more information about using a custom Maven `settings.xml` file, see [Using a Custom Maven Settings File](https://devcenter.heroku.com/articles/using-a-custom-maven-settings-xml).
11661

117-
License
118-
-------
62+
## Documentation
11963

120-
Licensed under the MIT License. See LICENSE file.
64+
For more information about using Java on Heroku, see the [Java Support](https://devcenter.heroku.com/categories/java-support) documentation on Dev Center.

0 commit comments

Comments
 (0)