Run a Plone site for testing#
This guide shows you how to start a Compose site: a throwaway Plone site with Volto and sample content, on your computer. The tutorials, the checks of this documentation, and the integration tests all use it.
You need Docker with Compose.
Start the site#
Download the Compose file, and start it.
curl -O https://raw.githubusercontent.com/plone/plone-client/main/docker-compose.yml
docker compose up --wait
--wait returns when the site answers, usually in less than a minute.
Open http://localhost:3000 to see the site, and log in with the user admin and the password admin.
These credentials belong to the throwaway Compose site; never reuse them on a real site.
To work on a copy of this repository, use the file at its root, which is the same one.
What the file starts#
# A Plone site with Volto and sample content, for tutorials and tests.
#
# docker compose up --wait start it; Volto answers at http://localhost:3000
# docker compose down -v stop it and throw everything away
#
# PLONE_PORT and VOLTO_PORT change the ports on your computer.
# make test-integration and make docs-check use this file too.
services:
plone:
image: ${PLONE_IMAGE:-plone/plone-backend:6.1}
environment:
SITE: Plone
TYPE: volto
ports:
- "${PLONE_PORT:-8080}:8080"
volto:
image: ${VOLTO_IMAGE:-plone/plone-frontend:19.6.1}
environment:
RAZZLE_INTERNAL_API_PATH: http://plone:8080/Plone
ports:
- "${VOLTO_PORT:-3000}:3000"
depends_on:
plone:
condition: service_healthy
# Creates the sample content once, and exits.
seed:
image: ghcr.io/astral-sh/uv:0.9-python3.13-alpine
command:
- uv
- run
- ${SEED_SCRIPT:-https://raw.githubusercontent.com/plone/plone-client/main/docs/_checks/seed.py}
environment:
PLONE_CLIENT_URL: http://plone:8080/Plone
PLONE_CLIENT_USERNAME: admin
PLONE_CLIENT_PASSWORD: admin
volumes:
- .:/repository:ro
depends_on:
plone:
condition: service_healthy
# The MCP server over HTTP: docker compose --profile mcp up --wait
# Clients send the token in $PLONE_CLIENT_MCP_TOKEN, of 32 characters or more.
mcp:
profiles: [mcp]
image: ghcr.io/astral-sh/uv:0.9-python3.13-alpine
command: uvx --from plone-client[mcp] plone-client mcp --http --host 0.0.0.0
environment:
PLONE_CLIENT_URL: http://plone:8080/Plone
PLONE_CLIENT_USERNAME: admin
PLONE_CLIENT_PASSWORD: admin
PLONE_CLIENT_FRONTEND_URL: http://volto:3000
PLONE_CLIENT_MCP_TOKEN: ${PLONE_CLIENT_MCP_TOKEN:-}
ports:
- "127.0.0.1:${MCP_PORT:-8000}:8000"
depends_on:
plone:
condition: service_healthy
Service |
What it is |
Address on your computer |
|---|---|---|
|
The backend, with a site with the id |
|
|
The frontend, which talks to the backend inside Docker. |
|
|
A script that creates the sample content, and exits. |
None |
|
Only with |
|
What the sample content is#
The seed service runs seed.py once, and skips what already exists.
Content |
State |
|---|---|
|
Published |
|
Private |
|
Published |
|
Private |
|
Pending |
|
No workflow |
|
No workflow |
|
|
|
Point a profile at it#
Set --frontend-url too, so that block-types can ask Volto which blocks the site has.
plone-client profile add local --url http://localhost:8080/Plone --username admin --frontend-url http://localhost:3000 --use
When asked for the password, type admin.
Check that it works.
plone-client ls /news -f id,review_state -c
[{"review_state": "published"}, {"review_state": "private"}, {"review_state": "private"}, {"review_state": "pending"}, {"review_state": "published"}]
Choose other versions or ports#
Environment variables change what the file starts.
Variable |
Default |
Changes |
|---|---|---|
|
|
The backend image. |
|
|
The frontend image. |
|
|
The port of the backend on your computer. |
|
|
The port of the frontend on your computer. |
For example, this runs Plone 6.2 on other ports, next to a site that uses the default ones.
PLONE_IMAGE=plone/plone-backend:6.2 PLONE_PORT=8081 VOLTO_PORT=3001 docker compose -p other up --wait
Reset the site#
Remove the containers and their data, and start again.
docker compose down -v
docker compose up --wait
This also recovers from a tutorial that failed half way; remove the profiles it created with plone-client profile remove NAME.
How the checks use it#
In a copy of this repository, make docs-check starts this site for each page, runs the page’s commands, compares their output with the page, and removes the site.
make test-integration starts the plone and volto services on free ports.