🚧 This instance is under construction; expect occasional downtime. Runners available in /repos. Questions? Ask in #wikimedia-gitlab on libera.chat, or under GitLab on Phabricator.

README.md 3.05 KB
Newer Older
Dduvall's avatar
Dduvall committed
1
![Blubber](docs/logo-400.png)
Dduvall's avatar
Dduvall committed
2
3
4
5
6
7
8
9
10

Blubber is a highly opinionated abstraction for container build configurations
and a command-line compiler which currently supports outputting multi-stage
Dockerfiles. It aims to provide a handful of declarative constructs that
accomplish build configuration in a more secure and determinate way than
running ad-hoc commands.

## Example configuration

11
```yaml
Thcipriani's avatar
Thcipriani committed
12
version: v4
13
14
15
base: debian:jessie
apt:
  packages: [libjpeg, libyaml]
16
lives:
17
  in: /srv/service
18
runs:
Dduvall's avatar
Dduvall committed
19
20
21
  environment:
    FOO: bar
    BAR: baz
22
23

variants:
24
  build:
25
26
    apt:
      packages: [libjpeg-dev, libyaml-dev]
27
    node:
28
      requirements: [package.json, package-lock.json]
29
    copies: [local]
30
31
32

  development:
    includes: [build]
33
34

  test:
35
    includes: [build]
36
37
38
39
    apt:
      packages: [chromium]
    entrypoint: [npm, test]

40
41
42
43
44
  prep:
    includes: [build]
    node:
      env: production

45
46
  production:
    base: debian:jessie-slim
47
    node:
48
      env: production
49
    copies: [prep]
50
    entrypoint: [node, server.js]
Dduvall's avatar
Dduvall committed
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
```

## Variants

Blubber supports a concept of composeable configuration variants for defining
slightly different container images while still maintaining a sufficient
degree of parity between them. For example, images for development and testing
may require some development and debugging packages which you wouldn't want in
production lest they contain vulnerabilities and somehow end up linked or
included in the application runtime.

Properties declared at the top level are shared among all variants unless
redefined, and one variant can include the properties of others. Some
properties, like `apt:packages` are combined when inherited or included.

In the example configuration, the `test` variant when expanded effectively
becomes:

69
```yaml
Thcipriani's avatar
Thcipriani committed
70
version: v4
71
72
73
base: debian:jessie
apt:
  packages: [libjpeg, libyaml, libjpeg-dev, libyaml-dev, chromium]
74
75
node:
  dependencies: true
Dduvall's avatar
Dduvall committed
76
runs:
77
78
79
80
81
  in: /srv/service
  as: runuser
  uid: 666
  gid: 666
entrypoint: [npm, test]
Dduvall's avatar
Dduvall committed
82
83
84
85
86
87
88
89
90
91
92
```

## Artifacts

When trying to ensure optimally sized Docker images for production, there's a
common pattern that has emerged which is essentially to use one image for
building an application and copying the resulting build artifacts to another
much more optimized image, using the latter for production.

The Docker community has responded to this need by implementing
[multi-stage builds](https://github.com/moby/moby/pull/32063) and Blubber
93
makes use of this with its `copies` configuration property.
Dduvall's avatar
Dduvall committed
94
95

In the example configuration, the `production` variant declares artifacts to
96
be copied over from the result of building the `prep` image.
Dduvall's avatar
Dduvall committed
97
98
99
100
101
102

## Usage

Running the `blubber` command will be produce `Dockerfile` output for the
given variant.

103
    blubber config.yaml variant
Dduvall's avatar
Dduvall committed
104
105

You can see the result of the example configuration by cloning this repo and
Giuseppe Lavagetto's avatar
Giuseppe Lavagetto committed
106
running (assuming you have go):
Dduvall's avatar
Dduvall committed
107

Giuseppe Lavagetto's avatar
Giuseppe Lavagetto committed
108
    make
109
110
111
    ./blubber blubber.example.yaml development
    ./blubber blubber.example.yaml test
    ./blubber blubber.example.yaml production
Dduvall's avatar
Dduvall committed
112
113
114
115
116

## Contribution

If you'd like to make code contributions to Blubber, see
[CONTRIBUTING.md](CONTRIBUTING.md).