Document the `plone/nick` container image by ericof · Pull Request #2119 · plone/documentation

ericof · 2026-10-31T02:26:48Z

The plone/nick image is published, but the Containers section doesn't mention it. This adds docs/install/containers/images/nick.md and lists it among the official images.

The new page covers:

what the image is, and how its tags move, including that published images are rebuilt in place, so an exact build needs the image digest
running Nick with PostgreSQL, with DB_PASSWORD and SECRET as the required settings
a Docker Compose stack that splits Nick into migrate, api and worker containers
configuration, and building your own image with add-ons, with ADDONS for trying them out only

The Compose stack lives on the image page, as it does for plone/aurora, rather than under examples/. Nick's deployment guidance stays in the Nick documentation, which the page links to.

Note for reviewers: without PROFILES, the image installs the demo site with an admin user whose password is admin. The page warns about this because it matters for anyone copying the examples to production.

The README's plain docker run example sets DB_HOST=db but starts no database that the container can reach under that name, so it fails with a host lookup error. The page creates a Docker network and a PostgreSQL container first, and runs Nick on that network.

Closes #2118

Add a page for the official plone/nick image: its tags, running it with PostgreSQL, a Docker Compose stack that splits the migrate, api and worker modules, selecting modules, the configuration variables and add-ons. The deployment guide of Nick is linked, not repeated. Add the image to the official images table and the toctree. Refs #2118

The docker run flow kept the database and uploaded files in the container, so removing a container lost them. Create the nick-data and nick-blobs volumes and mount them on the database and on Nick, and explain what each volume holds and what removing it deletes. The Compose section now says what its volumes hold and that docker compose down -v deletes them. Refs #2118

ericof · 2026-10-31T03:08:21Z

I'm merging as the dlr.de SSL failure is probably temporary

stevepiercy

Merged too quick. Would you please incorporate these changes, and see my questions? Thank you!

stevepiercy · 2026-10-31T02:48:45Z

+
+- `3.0` points to the newest 3.0.x release.
+- `3` points to the newest 3.x release.
+- `latest` points to the version in the `version.txt` file of the repository.


Suggested change

- `latest` points to the version in the `version.txt` file of the repository.

- `latest` points to the version in the {file}`version.txt` file of the repository.

stevepiercy · 2026-10-31T02:49:05Z

+- `latest` points to the version in the `version.txt` file of the repository.
+
+A prerelease, such as `3.1.0-alpha.1`, gets only its own tag.
+It does not move `latest`, `3` or `3.0`.


Suggested change

It does not move `latest`, `3` or `3.0`.

It does not move `latest`, `3`, or `3.0`.

stevepiercy · 2026-10-31T02:50:58Z

+Then use the digest in place of the tag, as `plone/nick@sha256:<digest>`.
+
+
+## Using this image


Suggested change

## Using this image

## Usage

This section describes how to use the `plone/nick` image.

stevepiercy · 2026-10-31T02:52:50Z

+### Run with PostgreSQL
+
+The image runs `nick`, which migrates the database, installs the profiles, and starts the API on port 8080 and the job worker.
+Set `DB_PASSWORD` and `SECRET`; the container stops at startup if either one is missing.


How should these be set?

stevepiercy · 2026-10-31T02:55:44Z

+
+A named volume is storage that Docker manages, and it outlives the container that uses it.
+The `nick-data` volume keeps the database, and the `nick-blobs` volume keeps the uploaded files in the default `file` blob storage.
+Without them, removing a container removes the data it holds.


Suggested change

Without them, removing a container removes the data it holds.

With these named volumes, it's possible to remove the container without removing the data and files it holds.

stevepiercy · 2026-10-31T03:06:42Z

+Read the [Add-ons](https://nick.docs.plone.org/developer-guide/addons) chapter of the Nick documentation for how to write one.
+
+The `ADDONS` variable installs add-ons every time the container starts.
+Use it only to try an add-on out, and build an image for production.


Suggested change

Use it only to try an add-on out, and build an image for production.

Use it only to try out an add-on, and build an image for production.

stevepiercy · 2026-10-31T03:07:13Z

+ENV PROFILES=@plone/nick:core,@acme/nick-addon:default
+```
+
+Read the [Add-ons](https://nick.docs.plone.org/developer-guide/addons) chapter of the Nick documentation for how to write one.


Got intersphinx? Not sure what Nick uses to build docs.

stevepiercy · 2026-10-31T03:07:51Z

+| `/app/config.ts` | A `config.ts` file mounted at this path replaces the environment configuration. |
+
+Nick reads other settings from the environment as well.
+For the full list, and for the settings of a production deployment, see the [Deployment](https://nick.docs.plone.org/admin-guide/deployment) guide in the Nick documentation.


Got intersphinx? Not sure what Nick uses to build docs.

stevepiercy · 2026-10-31T03:08:07Z

+| `NICK_MODULES` | Modules to run: `migrate`, `api` or `worker`, separated by commas. Default: all of them. |
+| `PORT` | Port where the API listens. Default: `8080`. |
+| `ALLOWED_ORIGINS` | Origins that CORS allows, such as the address of the frontend. |
+| `BLOBS_DIR` | Directory of the `file` blob storage. Default: `/app/var/blobstorage`. Mount a volume there, or use the `db` or `s3` blob storage. |


Suggested change

| `BLOBS_DIR` | Directory of the `file` blob storage. Default: `/app/var/blobstorage`. Mount a volume there, or use the `db` or `s3` blob storage. |

| `BLOBS_DIR` | Directory of the `file` blob storage. Default: {file}`/app/var/blobstorage`. Mount a volume there, or use the `db` or `s3` blob storage. |

stevepiercy · 2026-10-31T03:10:07Z

+
+The `migrate` module exits with a non-zero status when it hits errors.
+Each command needs the database and secret variables from the previous section.
+To set the modules with an environment variable instead, use `-e NICK_MODULES=api`.


Suggested change

To set the modules with an environment variable instead, use `-e NICK_MODULES=api`.

To set the modules with an environment variable instead.

For example, for the `api` module, use the following:

```shell

docker run plone/nick -e NICK_MODULES=api

```

Follow-up to #2119 with the changes stevepiercy requested. Say how to pass the required variables, show the commands that remove containers and volumes, and put the environment variable option before the image name, where docker run reads it.

github-project-automation Bot added this to Plone Documentation Oct 31, 2026

github-project-automation Bot moved this to New in Plone Documentation Oct 31, 2026

ericof requested a review from sneridagh October 31, 2026 02:30

sneridagh previously approved these changes Oct 31, 2026

View reviewed changes

github-project-automation Bot moved this from New to Approved in Plone Documentation Oct 31, 2026

ericof dismissed sneridagh’s stale review via 476c2cd October 31, 2026 02:49

ericof requested a review from sneridagh October 31, 2026 02:52

sneridagh approved these changes Oct 31, 2026

View reviewed changes

ericof merged commit 34dd9b8 into 6.0 Oct 31, 2026
2 of 4 checks passed

ericof deleted the issue-2118 branch October 31, 2026 03:08

github-project-automation Bot moved this from Approved to Done in Plone Documentation Oct 31, 2026

stevepiercy requested changes Oct 31, 2026

View reviewed changes

github-project-automation Bot moved this from Done to In Progress in Plone Documentation Oct 31, 2026

ericof mentioned this pull request Oct 31, 2026

Apply review suggestions to the plone/nick image page #2120

Merged

Navigation Menu

Repository navigation

Document the `plone/nick` container image - #2119

Document the `plone/nick` container image#2119
ericof merged 2 commits into
6.0from
issue-2118

ericof commented Oct 31, 2026

Uh oh!

ericof commented Oct 31, 2026

Uh oh!

Uh oh!

stevepiercy left a comment

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

stevepiercy Oct 31, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- `latest` points to the version in the `version.txt` file of the repository.
	- `latest` points to the version in the {file}`version.txt` file of the repository.

	It does not move `latest`, `3` or `3.0`.
	It does not move `latest`, `3`, or `3.0`.

		Then use the digest in place of the tag, as `plone/nick@sha256:<digest>`.


		## Using this image

-## Using this image
+## Usage
+This section describes how to use the `plone/nick` image.

	Without them, removing a container removes the data it holds.
	With these named volumes, it's possible to remove the container without removing the data and files it holds.

	Use it only to try an add-on out, and build an image for production.
	Use it only to try out an add-on, and build an image for production.

	\| `BLOBS_DIR` \| Directory of the `file` blob storage. Default: `/app/var/blobstorage`. Mount a volume there, or use the `db` or `s3` blob storage. \|
	\| `BLOBS_DIR` \| Directory of the `file` blob storage. Default: {file}`/app/var/blobstorage`. Mount a volume there, or use the `db` or `s3` blob storage. \|

-To set the modules with an environment variable instead, use `-e NICK_MODULES=api`.
+To set the modules with an environment variable instead.
+For example, for the `api` module, use the following:
+```shell
+docker run plone/nick -e NICK_MODULES=api
+```

Conversation

ericof commented Oct 31, 2026

Uh oh!

ericof commented Oct 31, 2026

Uh oh!

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants