README.rst 7.57 KB
Newer Older
Philippe Pepiot's avatar
Philippe Pepiot committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
CubicWeb docker images
======================

This project helps to build CubicWeb_ based applications as Docker_ images.
Builds include various versions of cubicweb and python and are using Debian_
base images.

.. _CubicWeb: https://www.cubicweb.org/
.. _Docker: https://www.docker.com/
.. _Debian: https://www.debian.org/

Tags
----

Images with cubicweb pre-installed:

* ``latest``, ``3.26``, ``py37-buster-3.26``
* ``dev``, ``py37-buster-dev`` (built using latest mercurial changeset)
* ``3.25``, ``py27-buster-3.25``
* ``py35-stretch-3.26``
* ``py27-buster-3.26``
* ``py27-stretch-3.25``
* ``py27-stretch-3.26``

Image without cubicweb installed:

* ``py37``, ``py37-buster``
* ``py35``, ``py35-stretch``
* ``py27``, ``py27-buster``
* ``py27-stretch``

32
33
34
35
36
Image for building debian packages:

* ``buildpackage``, ``buster-buildpackage``
* ``stretch-buildpackage``

Philippe Pepiot's avatar
Philippe Pepiot committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

What's included ?
-----------------

The image include required packages to build a cubicweb application image
suitable for production. It's designed to be used as a parent image for your
application Dockerfile.

The image contains:

* python with psycopg2
* /usr/bin/python and /usr/bin/pip are symlink to the selected python version (2.7, 3.5 or 3.7)
* gettex, graphviz
* uwsgi with a config file in /etc/uwsgi/uwsgi.ini
* a pyramid configuration templated from environment variables in /pyramid.ini
* a entrypoint to configure pyramid.ini, static data files in
  /etc/cubicweb.d/instance/data and automatic upgrade of database.

The entrypoint can also be used to run various command like database creation
with ``db-create`` or to run arbitrary commands.

The image has some expectations:

* The top level cube source code is expected to be found in /src directory. In
Denis Laxalde's avatar
Denis Laxalde committed
61
  case you install your cube elsewhere or from a pypi release, you will have to
Philippe Pepiot's avatar
Philippe Pepiot committed
62
63
64
  set the ``CUBE`` environment variable.

* The default instance name is "instance" and its configuration directory is in
Philippe Pepiot's avatar
Philippe Pepiot committed
65
66
  /etc/cubicweb.d/instance, this can be changed with the ``CW_INSTANCE``.
  Although you shouldn't need to modify this.
Philippe Pepiot's avatar
Philippe Pepiot committed
67
68
69
70
71


How to build an image for a cubicweb application ?
--------------------------------------------------

Denis Laxalde's avatar
Denis Laxalde committed
72
There are multiple ways to use theses images corresponding to different levels
Philippe Pepiot's avatar
Philippe Pepiot committed
73
74
of integration.

Denis Laxalde's avatar
Denis Laxalde committed
75
Here are some hints to make the best choice:
Philippe Pepiot's avatar
Philippe Pepiot committed
76
77
78
79

* Images with cubicweb pre-installed build faster
* Images without cubicweb pre-installed allow to use your own version of cubicweb
* ``onbuild`` images are useful when the Dockerfile in versioned in the source
Philippe Pepiot's avatar
Philippe Pepiot committed
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
  tree, except when your cube require a build toolchain to install. However
  they are DEPRECATED.

Example
~~~~~~~

For example, given you're in the source tree of `cubicweb-blog`_::

   FROM logilab/cubicweb:3.26
   USER root
   COPY . /src
   RUN pip install -e /src
   USER cubicweb
   RUN docker-cubicweb-helper create-instance


In case of out-of-source tree or not installing from /src directory, you will
also have to set the ``CUBE`` environment variable::

   FROM logilab/cubicweb:3.26
   USER root
   RUN pip install cubicweb-blog
   USER cubicweb
   ENV CUBE=blog
   RUN docker-cubicweb-helper create-instance
Philippe Pepiot's avatar
Philippe Pepiot committed
105
106
107
108

onbuild images
~~~~~~~~~~~~~~

Philippe Pepiot's avatar
Philippe Pepiot committed
109
110
.. warning:: A lot of magic happen with onbuild images. They are DEPRECATED.

Philippe Pepiot's avatar
Philippe Pepiot committed
111
112
113
114
115
116
117
118
119
120
All images have a ``onbuild`` version by adding the suffix ``-onbuild``.
The single tag ``onbuild`` is an alias for py37-buster-3.26-onbuild.

These images use the `ONBUILD intruction`_ to copy current code to the build
context and install your cube in develop mode and create an instance of your cube.

.. _ONBUILD intruction: https://docs.docker.com/engine/reference/builder/#onbuild

For example, given you're in the source tree of `cubicweb-blog`_, a Dockerfile would be as simple as::

121
   FROM logilab/cubicweb:onbuild
Philippe Pepiot's avatar
Philippe Pepiot committed
122
123
124

You can even build an image without actually writing any Dockerfile::

125
   echo "FROM logilab/cubicweb:onbuild" | docker build -f - -t cubicweb-blog .
Philippe Pepiot's avatar
Philippe Pepiot committed
126
127
128

In case you don't want a cubicweb version pre-installed and let your own dependencies control what version to install::

129
   FROM logilab/cubicweb:py37-onbuild
Philippe Pepiot's avatar
Philippe Pepiot committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194

.. _cubicweb-blog: https://hg.logilab.org/master/cubes/blog


How to run resulting images ?
-----------------------------

Environment variables control settings from ``all-in-one.conf``, most important are:

* ``CW_BASE_URL`` (default http://localhost:8080) should be set to the final url the instance will be accessed
  with. Including the scheme, for example: ``https://myapp.demo.logilab.org``

* ``CW_DB_DRIVER`` (default postgres), ``CW_DB_NAME``, ``CW_DB_USER`` and
  ``CW_DB_PASSWORD`` control database settings

* ``CW_LOGIN`` and ``CW_PASSWORD`` control the admin login and password,
  default to admin:admin

Quick testing using non persistent sqlite database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This can be used to validate your image actually works::

   docker run --rm -it -e CW_DB_NAME=db.sqlite myimage sh -c "cubicweb-ctl db-create -a instance && uwsgi --ini /etc/uwsgi/uwsgi.ini"

Then go to http://localhost:8080 to access your instance.


Create initial database
~~~~~~~~~~~~~~~~~~~~~~~

To create the initial database you will have to run ``db-create`` first:

For example::

   # Create the database on local postgresql cluster in a database named "myapp"
   docker run --rm -it -e CW_DB_NAME=myapp CW_DB_USER=me -v /var/run/postgresql:/var/run/postgresql myimage db-create

   # Create the database on remote postgresql server in a database named "myapp"
   docker run --rm -it -e CW_DB_NAME=myapp CW_DB_USER=me CW_DB_PASSWORD=secret CW_DB_HOST=dbserver myimage db-create

   # Create the database in a local /tmp/db.sqlite file
   docker run --rm -it -e CW_DB_NAME=/tmp/db.sqlite -v /tmp/db.sqlite:/tmp/db.sqlite myimage db-create

Run wsgi server
~~~~~~~~~~~~~~~

To start uwsgi server on local port 8080::

   # run foreground
   docker run --rm -it -p 8080:8080 myapp

   # run in background
   docker run -d --restart=always --name myapp myapp

Run looping tasks (aka scheduler)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To run cubicweb looping tasks, you will also have to start the ``scheduler``::

   # run foreground
   docker run --rm -it myapp cubicweb-ctl scheduler instance

   # run in background
   docker run -d --restart=always --name myapp-scheduler myapp cubicweb-ctl scheduler instance
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215


Best practices
--------------

In case of source tree builds, add a ``.dockerignore`` to your project to avoid
copying useless files inside the docker image. For example::

   .*
   *.egg-info
   **/__pycache__
   Dockerfile
   Jenkinsfile
   Makefile
   tox.ini
   test
   debian


Always pull the base image before running the build. Base images are rebuild in
case of debian security update or new pypi releases.
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245

buildpackage images
-------------------

These images can be used to build debian package(s) and publish them to a repo
located in /repo suitable for use within a multi-stage build.

Example, given all dependencies are available on "deb http://apt.logilab.fr buster cubicweb-3.26" repository and given you're working in the source tree of `cubicweb-blog`_::

   FROM logilab/cubicweb:buildpackage as buildpackage
   COPY . /src
   RUN buildpackage -d /src

   FROM logilab/cubicweb:3.26
   COPY --from=buildpackage /repo /repo
   RUN apt-get update && apt-get -y --no-install-recommends install cubicweb-blog
   ENV CUBE=blog
   USER cubicweb
   RUN docker-cubicweb-helper create-instance


If you need to build more packages, or build specific revisions, the
``buildpackage`` script can also build from an archive::

   FROM logilab/cubicweb:buster-buildpackage
   RUN buildpackage -u https://hg.logilab.org/master/cubes/comment/archive/tip.tar.gz
   COPY . /src
   RUN buildpackage -d /src

   [...]