Advanced usage¶
Grocker build chain can be customized using the command line interface or the
.grocker.yml
file (or the one defined through the --config
parameter). When both
are used, command line arguments take precedence.
The build command line interface¶
Usage: grocker [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
-v, --verbose
--help Show this message and exit.
Commands:
build Build docker image for <release> (version...
purge Purge Grocker created Docker stuff
Usage: grocker build [OPTIONS] RELEASE
Build docker image for RELEASE (version specifiers can be used).
RELEASE can either be the name of a project, or the path to a wheel to
use. In both cases, extra requirements can be applied:
grocker build your_project[with_extra]==1.2.3
grocker build /path/to/your_project-1.2.3.whl[with_extra]
Options:
-c, --config <filename> Grocker config file
-r, --runtime <runtime> runtime used to build and run this image
--pip-conf <filename> pip configuration file used to download
dependencies (by default use pip config
getter)
--pip-constraint <filename> pip constraint file used to download
dependencies
-e, --entrypoint <entrypoint> Docker entrypoint to use to run this image
--volume <volume> Container storage and configuration area
--port <port> Port on which a container will listen for
connections
--env <env=value> Additional environment variable for final image
--image-prefix <uri> docker registry or account on Docker
official registry to use
--image-base-name <name> base name for the image (eg '<image-
prefix>/<image-base-name>:<image-version>')
-n, --image-name <name> name used to tag the build image
--result-file <filename> yaml file where results (image name, ...)
are written
--build-dependencies / --no-build-dependencies
build the dependencies
--build-image / --no-build-image
build the docker image
--push / --no-push push the image
--help Show this message and exit.
Actions¶
Grocker splits the build chain into three steps:
dependencies
, compiles wheels and stores them in a data volume.image
, builds the runner image using stored wheels.push
, pushes the runner image on the configured Docker registry ( only if a docker image prefix is given)
This allows you, for example, to build an image without pushing it, then do some tests, and after your tests passed push the image.
Pip config¶
The --pip-conf
permits to select a specific pip config file. By default Grocker
uses the user pip config file.
.grocker.yml
config file¶
The .grocker.yml
allows to customise Grocker build by setting dependencies among other things.
It is written in YAML. By default, Grocker looks for this file in the current directory. Its default values are:
# .grocker.yml (defaults)
runtime: alpine/3
pip_constraint: # optional
volumes: []
ports: []
env: {}
repositories: {}
dependencies:
run: []
build: []
docker_image_prefix: # optional
image_base_name: # optional
entrypoint_name: grocker-runner
Dependencies¶
Two kind of dependencies can be declared those used on the final image (run
) and
those which will be installed only on the build image (build
).
Each package declared on those lists will be installed using the system package manager.
Repositories¶
Each item of the repositories
mapping is a mapping with two keys:
uri
: The deb line of the repositorykey
: The GPG key used to sign this repository packages
The first level mapping key is used as the repository identifier.
Example¶
An example with all options customised:
# .grocker.yml (full example)
runtime: jessie/2.7
pip_constraint: constraints.txt
volumes: ['/data', '/cache']
ports: [8080, 8081]
env:
SOME_ENV_VAR: value of the envvars
ANOTHER_ENV_VAR: 45
http_proxy: http://127.0.0.1:8080
repositories:
nginx:
uri: deb http://nginx.org/packages/debian/ jessie nginx
key: |
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.11 (FreeBSD)
mQENBE5OMmIBCAD+FPYKGriGGf7NqwKfWC83cBV01gabgVWQmZbMcFzeW+hMsgxH
W6iimD0RsfZ9oEbfJCPG0CRSZ7ppq5pKamYs2+EJ8Q2ysOFHHwpGrA2C8zyNAs4I
QxnZZIbETgcSwFtDun0XiqPwPZgyuXVm9PAbLZRbfBzm8wR/3SWygqZBBLdQk5TE
fDR+Eny/M1RVR4xClECONF9UBB2ejFdI1LD45APbP2hsN/piFByU1t7yK2gpFyRt
97WzGHn9MV5/TL7AmRPM4pcr3JacmtCnxXeCZ8nLqedoSuHFuhwyDnlAbu8I16O5
XRrfzhrHRJFM1JnIiGmzZi6zBvH0ItfyX6ttABEBAAG0KW5naW54IHNpZ25pbmcg
a2V5IDxzaWduaW5nLWtleUBuZ2lueC5jb20+iQE+BBMBAgAoBQJOTjJiAhsDBQkJ
ZgGABgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAKCRCr9b2Ce9m/YpvjB/98uV4t
94d0oEh5XlqEZzVMrcTgPQ3BZt05N5xVuYaglv7OQtdlErMXmRWaFZEqDaMHdniC
sF63jWMd29vC4xpzIfmsLK3ce9oYo4t9o4WWqBUdf0Ff1LMz1dfLG2HDtKPfYg3C
8NESud09zuP5NohaE8Qzj/4p6rWDiRpuZ++4fnL3Dt3N6jXILwr/TM/Ma7jvaXGP
DO3kzm4dNKp5b5bn2nT2QWLPnEKxvOg5Zoej8l9+KFsUnXoWoYCkMQ2QTpZQFNwF
xwJGoAz8K3PwVPUrIL6b1lsiNovDgcgP0eDgzvwLynWKBPkRRjtgmWLoeaS9FAZV
ccXJMmANXJFuCf26iQEcBBABAgAGBQJOTkelAAoJEKZP1bF62zmo79oH/1XDb29S
YtWp+MTJTPFEwlWRiyRuDXy3wBd/BpwBRIWfWzMs1gnCjNjk0EVBVGa2grvy9Jtx
JKMd6l/PWXVucSt+U/+GO8rBkw14SdhqxaS2l14v6gyMeUrSbY3XfToGfwHC4sa/
Thn8X4jFaQ2XN5dAIzJGU1s5JA0tjEzUwCnmrKmyMlXZaoQVrmORGjCuH0I0aAFk
RS0UtnB9HPpxhGVbs24xXZQnZDNbUQeulFxS4uP3OLDBAeCHl+v4t/uotIad8v6J
SO93vc1evIje6lguE81HHmJn9noxPItvOvSMb2yPsE8mH4cJHRTFNSEhPW6ghmlf
Wa9ZwiVX5igxcvaIRgQQEQIABgUCTk5b0gAKCRDs8OkLLBcgg1G+AKCnacLb/+W6
cflirUIExgZdUJqoogCeNPVwXiHEIVqithAM1pdY/gcaQZmIRgQQEQIABgUCTk5f
YQAKCRCpN2E5pSTFPnNWAJ9gUozyiS+9jf2rJvqmJSeWuCgVRwCcCUFhXRCpQO2Y
Va3l3WuB+rgKjsQ=
=A015
-----END PGP PUBLIC KEY BLOCK-----
dependencies:
run:
- libzbar0
- libjpeg62-turbo
- libffi6
- libtiff5
- nginx
build:
- libzbar-dev
- libjpeg62-turbo-dev
- libffi-dev
- libtiff5-dev
docker_image_prefix: docker.example.com
entrypoint_name: my-runner
Purging Grocker stuffs¶
The purge
command is here to clean Grocker created stuff of your Docker daemon.
Usage: grocker purge [OPTIONS]
Purge Grocker created Docker stuff
Options:
-a, --all-versions / --only-old-versions
-f, --including-final-images / --excluding-final-images
--help Show this message and exit.