logilab/cubicweb-base repository overview

⁠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.

⁠Tags

Images available:

• latest,
• 1.0,

⁠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 case you install your cube elsewhere or from a pypi release, you will have to set the CUBE environment variable.
• The default instance name is "instance" and its configuration directory is in /etc/cubicweb.d/instance, this can be changed with the CW_INSTANCE. Although you shouldn't need to modify this.

⁠How to build an image for a cubicweb application ?

There are multiple ways to use theses images corresponding to different levels of integration.

Here are some hints to make the best choice:

• Images with cubicweb pre-installed build faster
• Images without cubicweb pre-installed allow to use your own version of cubicweb

⁠Example

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

FROM logilab/cubicweb-base
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-base
USER root
RUN pip install cubicweb-blog
USER cubicweb
ENV CUBE=blog
RUN docker-cubicweb-helper create-instance

⁠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

⁠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.