|
1 | 1 | # Python Buildpack Binaries |
2 | 2 |
|
3 | | -## Building the Docker Images |
| 3 | +The binaries for this buildpack are built in Docker containers based on the Heroku stack image. |
4 | 4 |
|
5 | | -**After every change to your formulae, perform the following** from the root of the Git repository (not from `builds/`) to rebuild the images for each stack: |
6 | | - |
7 | | - $ docker build --pull --tag heroku-python-build-cedar-14 --file $(pwd)/builds/cedar-14.Dockerfile . |
8 | | - $ docker build --pull --tag heroku-python-build-heroku-16 --file $(pwd)/builds/heroku-16.Dockerfile . |
9 | | - $ docker build --pull --tag heroku-python-build-heroku-18 --file $(pwd)/builds/heroku-18.Dockerfile . |
| 5 | +## Configuration |
10 | 6 |
|
11 | | -## Using the Image |
| 7 | +In order to publish binaries AWS credentials must be passed to the build container. |
| 8 | +If you are testing only the build (ie: `bob build`), these are optional. |
12 | 9 |
|
13 | | -You can e.g. `bash` into each of the images you built using their tag: |
| 10 | +In addition, unless you are building the official binaries for Heroku (which use the defaults |
| 11 | +specified in each `Dockerfile`), you will need to override `S3_BUCKET` and `S3_PREFIX` to |
| 12 | +match your own S3 bucket/use case. |
14 | 13 |
|
15 | | - docker run --rm -ti heroku-python-build-cedar-14 bash |
16 | | - docker run --rm -ti heroku-python-build-heroku-16 bash |
17 | | - docker run --rm -ti heroku-python-build-heroku-18 bash |
| 14 | +If you only need to set AWS credentials, you can do so by setting the environment variables |
| 15 | +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` before calling the make commands. |
18 | 16 |
|
19 | | -You then have a shell where you can run `bob build`, `bob deploy`, and so forth. You can of course also invoke these programs directly with `docker run`: |
| 17 | +For example: |
20 | 18 |
|
21 | | - docker run --rm -ti heroku-python-build-heroku-18 bob build runtimes/python-2.7.15 |
| 19 | +```bash |
| 20 | +set +o history # Disable bash history |
| 21 | +export AWS_ACCESS_KEY_ID=... |
| 22 | +export AWS_SECRET_ACCESS_KEY=... |
| 23 | +set -o history # Re-enable bash history |
| 24 | +make ... |
| 25 | +``` |
22 | 26 |
|
23 | | -In order to `bob deploy`, AWS credentials must be set up, as well as name and prefix of your custom S3 bucket (unless you're deploying to the Heroku production buckets that are pre-defined in each `Dockerfile`); see next section for details. |
| 27 | +If you need to override the default S3 bucket, or would prefer not to use credentials via |
| 28 | +environment variables, then you need to instead use a Docker env file like so: |
24 | 29 |
|
25 | | -## Configuration |
| 30 | +1. Copy the `builds/dockerenv.default` env file to a location outside the buildpack repository. |
| 31 | +2. Edit the new file, adding at a minimum the values for the variables |
| 32 | + `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (see Docker |
| 33 | + [env-file documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)). |
| 34 | +3. Pass the path of the file to the make commands using `ENV_FILE`. For example: |
26 | 35 |
|
27 | | -File `dockerenv.default` contains a list of required env vars; most of these have default values defined in `Dockerfile`. You can copy this file to a location outside the buildpack and modify it with the values you desire and pass its location with `--env-file`, or pass the env vars to `docker run` using `--env`. |
| 36 | + ```bash |
| 37 | + make ... ENV_FILE=~/.dockerenv.python-buildpack |
| 38 | + ``` |
28 | 39 |
|
29 | | -Out of the box, each `Dockerfile` has the correct values predefined for `S3_BUCKET`, `S3_PREFIX`, and `S3_REGION`. If you're building your own packages, you'll likely want to change `S3_BUCKET` and `S3_PREFIX` to match your info. Instead of setting `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` into that file, you may also pass them to `docker run` through the environment, or explicitly using `--env`, in order to prevent accidental commits of credentials. |
| 40 | +## Launching an interactive build environment |
30 | 41 |
|
31 | | -### Passing AWS credentials to the container |
| 42 | +To start an interactive version of the build environment (ideal for development) use the |
| 43 | +`buildenv` make target, passing in the desired `STACK` name. For example: |
32 | 44 |
|
33 | | -If you want to deploy packages and thus need to pass `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, you can either pass them explicitly, through your environment, or through an env file. |
| 45 | +```bash |
| 46 | +make buildenv STACK=heroku-18 |
| 47 | +``` |
34 | 48 |
|
35 | | -#### Passing credentials explicitly |
| 49 | +This will create the builder docker image based on the latest image for that stack, and |
| 50 | +then start a bash shell where you can run `bob build`, `bob deploy`, and so forth. |
36 | 51 |
|
37 | | - docker run --rm -ti -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... heroku-python-build-heroku-18 bash |
| 52 | +The `builds/` directory is bind-mounted into the running container, so local build formula |
| 53 | +changes will appear there immediately without the need to rebuild the image. |
38 | 54 |
|
39 | | -#### Passing credentials through the environment |
| 55 | +## Bulk deploying runtimes |
40 | 56 |
|
41 | | -The two environment variables `AWS_ACCESS_KEY_ID`and `AWS_SECRET_ACCESS_KEY` are defined in `builds/dockerenv.default`, without values. This will cause Docker to "forward" values for these variables from the current environment, so you can pass them in: |
| 57 | +When a new Python version is released, binaries have to be generated for multiple stacks. |
| 58 | +To automate this, use the `deploy-runtimes` make target, which will ensure the builder |
| 59 | +image is up to date, and then run `bob deploy` for each runtime-stack combination. |
42 | 60 |
|
43 | | - AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... docker run --rm -ti --env-file=builds/dockerenv.default heroku-python-build-heroku-18 bash |
| 61 | +The build formula name(s) are passed using `RUNTIMES`, like so: |
44 | 62 |
|
45 | | -or |
| 63 | +```bash |
| 64 | +make deploy-runtimes RUNTIMES='python-X.Y.Z' |
| 65 | +``` |
46 | 66 |
|
47 | | - export AWS_ACCESS_KEY_ID=... |
48 | | - export AWS_SECRET_ACCESS_KEY=... |
49 | | - docker run --rm -ti --env-file=builds/dockerenv.default heroku-python-build-heroku-18 bash |
| 67 | +By default this will deploy to all supported stacks (see `STACKS` in `Makefile`), |
| 68 | +but this can be overridden using `STACKS`: |
50 | 69 |
|
51 | | -#### Passing credentials through a separate env file |
| 70 | +```bash |
| 71 | +make deploy-runtimes RUNTIMES='python-X.Y.Z' STACKS='heroku-16 heroku-18' |
| 72 | +``` |
52 | 73 |
|
53 | | -This method is the easiest for users who want to build packages in their own S3 bucket, as they will have to adjust the `S3_BUCKET` and `S3_PREFIX` environment variable values anyway from their default values. |
| 74 | +Multiple runtimes can also be specified (useful for when adding a new stack), like so: |
54 | 75 |
|
55 | | -For this method, it is important to keep the credentials file in a location outside the buildpack, so that your credentials aren't accidentally committed. Copy `builds/dockerenv.default` **to a safe location outside the buildpack directory**, and insert your values for `AWS_ACCESS_KEY_ID`and `AWS_SECRET_ACCESS_KEY`. |
| 76 | +```bash |
| 77 | +make deploy-runtimes RUNTIMES='python-A.B.C python-X.Y.Z' STACKS='heroku-20' |
| 78 | +``` |
56 | 79 |
|
57 | | - docker run --rm -ti --env-file=../SOMEPATHOUTSIDE/s3.env heroku-python-build-heroku-18 bash |
| 80 | +Note: Both `RUNTIMES` and `STACKS` are space delimited. |
0 commit comments