Skip to content

Update container images and examples documentation - #2105

Merged
ericof merged 6 commits into
6.0from
issue-2103
Sep 15, 2026
Merged

Update container images and examples documentation#2105
ericof merged 6 commits into
6.0from
issue-2103

Conversation

@ericof

@ericof ericof commented Sep 12, 2026

Copy link
Copy Markdown
Member

Issue number

Description

Container images (#2103)

  • Update the links to the renamed repositories: container-backend, container-frontend, container-zeo, and container-historical.
  • Add a page for the plone/aurora image.
  • Add a page for the historical plone/plone images, from Plone 1.0 to 5.2.
  • Split the images index into official images for Plone 6 and other container images.

Container examples (#2104)

  • Move the Docker Compose examples to examples/compose, and add a Traefik version of every nginx example.
  • Add Docker Swarm stacks in examples/swarm for every Traefik example, aligned with cookieplone-templates: Let's Encrypt certificates, a Docker socket proxy, a table of environment variables, and HTTPS-only access.
  • Use source replacements for image versions: {PLONE_FRONTEND_VERSION}, {PLONE_ZEO_VERSION}, {TRAEFIK_VERSION}, and {POSTGRES_VERSION}.
  • Name the data volumes vol-site-data, stop publishing database ports, and remove duplicate keys from the Traefik and Varnish example.
  • Add HAProxy, Let's Encrypt, nginx, and Traefik to the Vale vocabulary.

This PR also adds .venv to .gitignore.

Testing

  • Started each new Docker Compose Traefik example with Docker, and checked routing through Traefik, the Virtual Host Monster rewrite of /++api++, and load balancing across two backends in the ZEO and PostgreSQL examples.
  • Rendered every Docker Compose example with docker compose config, and every Docker Swarm stack with docker stack config, with and without the required environment variables.
    The Swarm stacks haven't been deployed to a cluster.
  • Vale reports no errors, and the Sphinx build reports no warnings, for the changed pages.

Warning

@ericof
Add Aurora and historical container image pages
11be1aa 
- Add pages for the `plone/aurora` and historical `plone/plone` container images.
- Split the container images index into official images for Plone 6 and other images.
- Point links to the renamed GitHub repositories: `plone/container-backend`, `plone/container-frontend`, `plone/container-zeo`, and `plone/container-historical`.
- Fix Vale errors in the backend image page and the containers overview.
- Add Aurora and Podman to the Vale vocabulary.

Closes #2103
@ericof
Add .venv to .gitignore
d0e8499
@ericof
Update container examples and add Docker Swarm stacks
e1494a5 
- Move the Docker Compose examples to examples/compose, and add Traefik
  versions of every nginx example: traefik-volto-plone,
  traefik-volto-plone-zeo, traefik-volto-plone-postgresql, and
  traefik-plone.
- Add Docker Swarm stacks in examples/swarm for every Traefik example,
  aligned with cookieplone-templates: Let's Encrypt certificates, a Docker
  socket proxy, a table of environment variables, and HTTPS-only access.
- Use source replacements for image versions: PLONE_FRONTEND_VERSION,
  PLONE_ZEO_VERSION, TRAEFIK_VERSION, and POSTGRES_VERSION.
- Name the data volumes vol-site-data, stop publishing database ports,
  and remove duplicate keys from the Traefik and Varnish example.
- Add HAProxy, Let's Encrypt, nginx, and Traefik to the Vale vocabulary.

Closes #2104
@ericof
ericof requested a review from stevepiercy September 12, 2026 21:01
stevepiercy
stevepiercy requested changes Sep 12, 2026
View reviewed changes

@stevepiercy stevepiercy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did a quick review only. The suggestions are global changes I'd like to see applied before I do a thorough review. Thank you!

Comment thread docs/conf.py Outdated
Comment thread docs/install/containers/examples/compose/index.md Outdated
Comment thread docs/install/containers/examples/compose/traefik-plone.md Outdated
Comment thread docs/install/containers/examples/compose/traefik-plone.md Outdated
Comment thread docs/install/containers/examples/compose/traefik-plone.md Outdated
Comment thread docs/install/containers/examples/compose/traefik-plone.md
@github-project-automation github-project-automation Bot moved this from New to In Progress in Plone Documentation Sep 12, 2026
@ericof
Address review of container images and examples documentation
ec15a37 
- Use the {doc} role for links to documents under docs/install/containers.
- Use the {file} role for files and directories.
- Read image tags from required STACK_*_TAG environment variables in the
  Docker Compose and Docker Swarm examples, and document them in an
  "Environment variables" table on each example.
- Rename STACK_FRONT_REPLICAS and STACK_BACK_REPLICAS to
  STACK_FRONTEND_REPLICAS and STACK_BACKEND_REPLICAS.
- Define the container image versions once in conf.py, and use them in both
  myst_substitutions and source_replacements. source_replace now skips
  {{KEY}}, so it doesn't break MyST substitutions.
@ericof

ericof commented Sep 12, 2026

Copy link
Copy Markdown
Member Author

Thanks for the review, @stevepiercy! I applied the global changes under docs/install/containers.

  • {doc} role: Done
  • {file} role: Done

Substitutions

MyST doesn't expand substitutions inside code blocks, so source_replacements is still needed there, as your comment in conf.py says: replacements for code blocks that are not supported in rst_epilog or other substitutions.

To reduce the placeholders in code, the example YAML files now read the image tags from environment variables, such as STACK_BACKEND_TAG, documented in a new "Environment variables" table on each example. Everywhere outside code blocks, such as those tables, I've used the new format with {{PLONE_BACKEND_MINOR_VERSION}}.

I defined a new variable container_image_versions and reused it in myst_substitutions and in source_replacements, so we keep just one copy of the values. source_replace now skips {{KEY}}, because the plain string replacement was turning {{PLONE_FRONTEND_VERSION}} into {19}.

@ericof
ericof requested a review from stevepiercy September 12, 2026 23:29
davisagli
davisagli reviewed Sep 13, 2026
View reviewed changes

@davisagli davisagli left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technical review: looks good to me.

Comment thread docs/install/containers/examples/compose/index.md Outdated
Comment thread docs/install/containers/examples/swarm/index.md Outdated
Comment thread docs/install/containers/images/index.md
sneridagh
sneridagh reviewed Sep 14, 2026
View reviewed changes

@sneridagh sneridagh left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aside from @davisagli comments, LGTM. Humungous work! and very much needed.

Only to mention that I've pushed for a PR in Aurora templates for fixing the Dockerfile (it had a bug).

Along with plone/container-aurora#4 will work.

@ericof
Differentiate titles and descriptions of container examples
4eec50b 
- Give the Docker Compose and Docker Swarm index pages their own
  headings and metadata instead of repeating the parent page's.
- Move "Docker Swarm" from the start to the end of the swarm example
  headings and titles.
- Start each example description with what distinguishes its stack,
  and keep description and og:description identical.
- Fix the Varnish compose example metadata (missing ZEO, "Traefik
  Proxy" naming), a trailing comma in keywords, and a "Postgres"
  spelling error.
- List the Aurora image last in the container images table.
@ericof
ericof requested a review from davisagli September 15, 2026 20:53
davisagli
davisagli approved these changes Sep 15, 2026
View reviewed changes

@davisagli davisagli left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ericof thanks!

@ericof
ericof merged commit d3a9cb0 into 6.0 Sep 15, 2026
3 checks passed
@ericof
ericof deleted the issue-2103 branch September 15, 2026 23:23
@github-project-automation github-project-automation Bot moved this from In Progress to Done in Plone Documentation Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sneridagh sneridagh sneridagh left review comments
@davisagli davisagli davisagli approved these changes
@stevepiercy stevepiercy Awaiting requested review from stevepiercy

Assignees

No one assigned

Labels

None yet

Projects

Plone Documentation
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Update "Examples of Plone 6 setup with containers" Rename repositories for container images

4 participants

@ericof @davisagli @stevepiercy @sneridagh