1 | # Contributing
|
2 |
|
3 | You want to add new language support? Awesome!
|
4 | Figured out a way to seamlessly integrate with docker-compose and addons? Even better!
|
5 | We're in the very early stages of exploring the possibilities of Docker + Heroku,
|
6 | so all ideas are welcome.
|
7 |
|
8 | The simplest way to get started is to clone the repo and symlink it to your
|
9 | local Heroku client:
|
10 |
|
11 | ```
|
12 | make link
|
13 | ```
|
14 |
|
15 | When you'd like to go back to using the official release:
|
16 |
|
17 | ```
|
18 | make unlink
|
19 | heroku plugins:install heroku-docker
|
20 | ```
|
21 |
|
22 | While developing, you can run the basic test suite:
|
23 |
|
24 | ```
|
25 | npm test
|
26 | ```
|
27 |
|
28 | ## Platform API
|
29 |
|
30 | All of the language support is in [/platforms](/platforms).
|
31 | To support a new platform, create a new directory with an index.js that
|
32 | exposes the following fields:
|
33 |
|
34 | ### `name {String}`
|
35 |
|
36 | The name of the platform (node, java, etc).
|
37 |
|
38 | ### `detect(dir) {Function:Boolean}`
|
39 |
|
40 | A function that returns `true` only if you detect that your platform is
|
41 | probably present in `dir`. For example, the node platform checks for
|
42 | the presence of a `package.json` file.
|
43 |
|
44 | ### `getDockerfile(dir) {Function:String}`
|
45 |
|
46 | A function that returns the contents of a Dockerfile as a string.
|
47 | This Dockerfile will be used as the executable Dockerfile for
|
48 | projects running your platform.
|
49 |
|
50 | Two image types are created from each Dockerfile. The first is the
|
51 | `exec` image, which is used for a development environment. For example,
|
52 | node uses the `exec` image to run commands like `npm install` so that installed
|
53 | dependencies will be built for Heroku's Cedar-14 (Ubuntu) platform.
|
54 |
|
55 | The second image type is used for `start` and for `release`, and it's
|
56 | created via a 1-line temporary Dockerfile inheriting (FROM) the `exec` image.
|
57 |
|
58 | Thus, when you write your Dockerfile, if you want commands to be run
|
59 | only in the `start` and `release` phases, you should prefix those commands
|
60 | with `ONBUILD`.
|
61 |
|
62 | The best way to start is by checking out the
|
63 | [existing code in platforms](/platforms).
|
64 |
|
65 | ## Documentation
|
66 |
|
67 | Once you've got a working platform, be sure to document how to use it
|
68 | with at least one example. One of the coolest parts about this Docker
|
69 | workflow is how easy it is to get started quickly. Since all dependencies
|
70 | are self-contained, you should be able to create a hello-world type
|
71 | example that doesn't require the user to install anything new.
|
72 |
|
73 | ## Pull requests
|
74 |
|
75 | When your changes are ready, just send a PR!
|