Step-by-step: Using Docker to Set Up Plone 6

Plone has been under active development since its creation over 20 years ago, and it continues to evolve. Along with all of Plone 6’s front-end changes and those under the covers, we are now seeing Plone’s deployment story moving to Docker. Below, you’ll find a step-by-step guide to deploying Plone 6 with ease using the official Docker images maintained by the Plone release team.

Plone 6 Changes

There are many changes visible to end users in Plone 6, which is currently in alpha and is scheduled to be released later this year (2022).

Plone‘s new Volto React front-end looks vastly different and modern. It is an incredibly fast UI that talks to the Plone back end via the REST API included in Plone core.

For users of Plone’s server-side rendered front-end, now referred to as “Plone Classic,” things look familiar, although Plone 6 includes significant changes: the Barceloneta LTS theme, webpack and ES6 support. The most visible change for Classic users are probably the fun, new control panel icons

‍

Beneath the Surface of Plone 6: from buildout to pip

There is a big change for Plone 6 under the covers: Plone no longer uses the venerated (or, on occasion, the cursed) buildout tool, whose list of committers reads like a who’s who of early Python, Zope and Plone stars.

Plone is now installed using Python’s standard pip tool, the package installer for Python, which provides a consistent installation of Plone’s dependencies every time it is run.

Plone Docker Images

Plone has been available as community-maintained Docker images for several years now. Those images set up the Classic server-side rendered front-end.

With Plone 6 now shipping with the Volto React front-end, two Docker images are needed to run Plone: one for the Classic back-end which includes the REST API and one for the front-end which includes Node.js.

Plone 6’s Docker deployments now consist of these two images and are officially maintained by the Plone release team.

Let’s take a look at those new Docker images.

The Back-End Plone Docker Image

The Plone 6 back-end Docker image is available on GitHub. The image contains Plone installed using its new pip method and configured to use the default Data.fs ZODB file storage.

To try out the Plone 6 back end Docker image:

• Make sure you have Docker installed (or equivalent) and that the Docker daemon is running (see Docker installation instructions here).
• In a terminal or shell, run the command

docker run -e SITE=Plone -e TYPE="classic" -e SETUP_CONTENT=1 -p 8080:8080 plone/plone-backend:6.0.0a4 start

‍

Docker Environment Variables

The environment variable SITE lets you specify the ID of a site that should be created on startup.

The environment variable TYPE lets you specify whether to create a site that can be used with a Volto front-end (if set to "volto", the default); otherwise, if set to "classic" it will not include the installation of the built in REST API and configuration required for the Volto front-end.

The environment variable SETUP_CONTENT takes the value 1 or 0; if set to 1 then the default content for a new Plone site is loaded. This default content includes a front page, News and Events folders, and matching collections.

You can find more Plone Docker environment variables listed in the following places:

• Plone documentation
• Docker Hub
• GitHub repository

Viewing your Plone Site

If you prefer not to have a new Plone site created automatically, you can run the docker command without the -e environment variable arguments:

docker run -p 8080:8080 plone/plone-backend:6.0.0a4 start

Docker will pull down the image and start it. After a minute or two, depending on your internet connection and the speed of your computer, you will see messages like these:

Starting server in PID 1.
127.0.0.1 - - [08/Mar/2022:21:00:06 +0000] "GET /ok HTTP/1.1" 200 2 "-" "Wget"

This image serves Plone so it is listening on port 8080. You can use your browser to go to http://localhost:8080/ to see the Plone admin page.

(You may get an error if instead you try to browse to http://0.0.0.0:8080. Also note the protocol to use is http, not https).

If you’re prompted to log in, use the username admin and password admin.

Click “View your Plone site” and you will be taken to http://localhost:8080/Plone.

How to Create a Plone Site Manually

When you install Plone, by default there is no site created yet. To create a new site to use with Volto, press “Create a new Plone site;” to create a new Classic site, press “Create Classic Plone site.”

IMPORTANT: if you plan to run this in a public environment, you should change the default passwords and accounts. See this step-by-step process after the blog Conclusion.*

How to Extend the Plone Back-End Docker Image

The Plone back-end Docker image contains no add-ons, only default Plone.

You can extend Plone inside this Docker image by specifying the packages you want to add to it. For example, the following Dockerfile extends the image with the add-on called pas.plugins.authomatic:

FROM plone/plone-backend:6.0.0a4
RUN ./bin/pip install "pas.plugins.authomatic --use-deprecated legacy-resolver"

Note: the --use-deprecated legacy-resolver option is required for now because of a bug in pip.

ZEO Server

The Plone back-end Docker image supports ZEO clusters (multiple clients communicating with a server that manages access to the Data.fs file storage).

You can enable ZEO support by creating a docker-compose.yml file that also includes HAProxy as a load balancer in front of the ZEO clients. See the instructions at https://github.com/plone/plone-backend/#zeo-server.

The Front-End Plone Docker Image

To use Plone 6’s new Volto React front-end, use the Docker configurations at https://github.com/plone/plone-frontend.

You can choose from several example configurations, all currently using Python 3.9:

• Volto front end + Plone back end (ZODB with Data.fs filestorage)
• Volto front end + Plone back end (ZEO server and 2 ZEO clients)
• Volto front end + Plone back end (PostgreSQL + RelStorage)

In the following, we will use the simplest configuration, Volto + Plone (ZODB), which configures the Plone back end to listen on port 8080.

In a terminal or shell, enter:

git clone https://github.com/plone/plone-frontend.git
cd plone-frontend/examples/webserver-volto-plone

You can start everything in the foreground to see what’s happening:

docker-compose up

You will see a lot of messages scroll by:

Starting webserver-volto-plone_backend_1 ... done
Starting webserver-volto-plone_frontend_1 ... done
Starting webserver-volto-plone_webserver_1 ... done
...
backend_1    | 2022-04-15 19:20:52 INFO [Zope:42][MainThread] Ready to handle requests
backend_1    | 2022-04-15 19:20:52 INFO [waitress:485][MainThread] Serving on http://0.0.0.0:8080
...
frontend_1   | Volto is running in SEAMLESS mode
frontend_1   | 🎭 Volto started at http://localhost:3000 🚀
backend_1    | Starting server in PID 1.
backend_1    | 127.0.0.1 - - [15/Apr/2022:19:20:59 +0000] "GET /ok HTTP/1.1" 200 2 "-" "Wget"

Once you see that the back-end is ok and that Volto has started, you can create the Plone site.

(If you try to view the Volto front end before creating the new site, you’ll see an error message This page does not seem to exist… because it tries to connect to a nonexistent site).

Browse to http://localhost:8080 to view the Plone admin page in the back end:

Click “Create a new Plone site”:

You can leave the default values and press “Create Plone Site.”

Volto is served on port 3000, but because this Docker image also includes and configures the nginx web server to proxy the Volto front-end, you don’t need to specify the port number.

Browse to http://localhost (verify that you’re using http and not https; SSL is not set up by default):

While you have been doing this, your terminal window or shell has had numerous info messages scroll by because you started these Docker images in the foreground.

To run the images in the background (as daemons), first stop the foreground images by typing Control-C and waiting until all three images have stopped:

Gracefully stopping... (press Ctrl+C again to force)
Stopping webserver-volto-plone_webserver_1 ... done
Stopping webserver-volto-plone_frontend_1  ... done
Stopping webserver-volto-plone_backend_1   ... done

Use this command to run the images as daemons:

docker-compose up -d

Persisting Data

In the above instructions, we have not been concerned with persistent storage. Between docker run commands, it is possible for the Docker containers to be reset so any Plone or Volto sites you created will have been lost.

To avoid losing sites you created with these containers, you will need to tell Docker to create persistent storage.

You can find out how to create and use Docker persistent volumes on these sites:

• https://github.com/plone/plone-backend#readme
• https://docs.docker.com/storage/
• https://docs.docker.com/storage/volumes/

Conclusion

You can now deploy Plone 6 more easily and scalably using the official Docker images maintained by the Plone release team. Trying Plone is now as easy as running a single Docker command, and you can use these images to deploy Plone to the cloud.

You can choose to use Plone 6’s Classic front end (the mature server-side rendered interface), or its new, modern, blazing fast Volto front-end.

Thanks to Érico Andrei, Plone Foundation President, who helped develop and streamline a lot of the Docker deployment recipes and training, including https://github.com/collective/plone6-local-demo.

*Changing Default Passwords and Accounts

IMPORTANT: if you plan to run this in a public environment, you should change the admin password by browsing to http://localhost:8080/acl_users/users/manage_users and clicking on the “Password” link.

To make your new site even more secure, replace the admin user with a new user with the same Manager role.

• Browse to http://localhost:8080/acl_users/users/manage_users.

‍

• Click “Add a user” and create a new user (in this example, we add a user bloodhound).

‍

• Browse to http://localhost:8080/acl_users/roles/manage_roles.
• Click the pencil icon next to admin in the Assignments column.

‍

‍

• In the “Enter Principal ID” text field, enter the ID of the new user you created.

• Press Search.

• Click on the new user you created to select it (in this example, the new user ID is bloodhound).

• Click on the right arrow icon to grant your new user Manager role.

• Then return to http://localhost:8080/acl_users/users/manage_users, check the box next to admin and press Remove Users to delete it.