diff --git a/docs/install/containers/examples/index.md b/docs/install/containers/examples/index.md index 5af7f6315..1d4424ccd 100644 --- a/docs/install/containers/examples/index.md +++ b/docs/install/containers/examples/index.md @@ -9,6 +9,8 @@ myst: # Examples of Plone 6 using containers +This section provides examples of how to use Plone 6 with container orchestration tools and various deployment configurations. + ```{toctree} :maxdepth: 2 :hidden: true @@ -21,7 +23,47 @@ haproxy-plone-zeo traefik-volto-plone-varnish ``` -Examples of projects running Plone using `docker compose`. +## Container orchestration + +Plone 6 can be deployed using various container orchestration tools: + +### Docker Compose + +Most examples in this section use {term}`Docker Compose` for orchestrating multiple containers. +Docker Compose is ideal for development, testing, and small to medium deployments. + +All the examples below use `docker compose` (or `docker-compose` in older versions) to manage multi-container setups. + +### Docker Swarm + +For production deployments requiring high availability and scaling, you can use Docker Swarm mode. +Docker Swarm provides native clustering capabilities for Docker containers, allowing you to: + +- Deploy services across multiple nodes +- Scale services up or down +- Manage rolling updates +- Provide service discovery and load balancing + +To use Docker Swarm with Plone, you can convert `docker-compose.yml` files to Docker Swarm stack files. +The basic structure remains similar, but you may need to adjust networking and volume configurations for multi-node deployments. + +```{seealso} +For more information about production orchestration with Docker Swarm, see {doc}`/deployment/orchestration`. +``` + +### Other orchestration tools + +Plone 6 container images are OCI-compliant and can be used with other orchestration platforms: + +- **Kubernetes**: For large-scale, production deployments with advanced features like auto-scaling, self-healing, and service mesh integration +- **Podman Compose**: An alternative to Docker Compose that works with Podman +- **Nomad**: HashiCorp's container orchestration platform + +The examples provided here focus on Docker Compose, but the concepts can be adapted to other orchestration tools. + +## Example configurations + +Examples of projects running Plone using `docker compose`: | Project example | Description | | --- | --- | diff --git a/docs/install/containers/getting-started.md b/docs/install/containers/getting-started.md new file mode 100644 index 000000000..758fa8da7 --- /dev/null +++ b/docs/install/containers/getting-started.md @@ -0,0 +1,80 @@ +--- +myst: + html_meta: + "description": "How to get started with Plone 6 containers" + "property=og:description": "How to get started with Plone 6 containers" + "property=og:title": "Getting started with containers" + "keywords": "Plone 6, install, installation, Docker, containers, getting started" +--- + +(install-containers-getting-started-label)= + +# Getting started with containers + +```{note} +Although there are many container engine tools for developing, managing, and running containers, we will use {term}`Docker` in this documentation. +``` + + +(install-containers-index-system-requirements-label)= + +## System requirements + +The system requirements include those required by Docker itself. + +- [Linux](https://docs.docker.com/desktop/setup/install/linux/) +- [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) +- [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) + +Plone 6 itself requires memory and disk space in addition to those of Docker alone. +See its {ref}`create-project-cookieplone-hardware-requirements-label`. + + +## Install Docker + +Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/) for your operating system. + +Docker Desktop includes all Docker tools. +{term}`Docker Compose` is one of the Docker tools that will be used in much of this documentation. + + +## Start Plone + +First start the Plone Backend, naming it `plone6-backend` and creating a site with its default configuration, using the following command. + +```shell +docker run --name plone6-backend -e SITE=Plone -d -p 8080:8080 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} +``` + +Now start the Plone Frontend, linking it to the `plone6-backend`: + +```shell +docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest +``` + + +## Access your Plone site + +Point your browser to `http://localhost:3000` and you should see the new Plone site. + +```{note} +The default user is `admin` and the password is `admin`. +``` + + +## Shutdown and cleanup + +To stop and clean up the containers use the following commands. + +```shell +docker stop plone6-frontend && docker rm plone6-frontend +docker stop plone6-backend && docker rm plone6-backend +``` + + +## Next steps + +Get to know the [Official Images](images/index) maintained by the Plone community. + +Also see some [examples](examples/index) of how to use the Official Images to bootstrap your projects. + diff --git a/docs/install/containers/images/backend-reference.md b/docs/install/containers/images/backend-reference.md new file mode 100644 index 000000000..c4591fff8 --- /dev/null +++ b/docs/install/containers/images/backend-reference.md @@ -0,0 +1,128 @@ +--- +myst: + html_meta: + "description": "Reference for plone/plone-backend image environment variables" + "property=og:description": "Reference for plone/plone-backend image environment variables" + "property=og:title": "Plone Backend image - Environment Variables Reference" + "keywords": "Plone 6, install, installation, docker, containers, backend, plone/plone-backend, reference, environment variables" +--- + +# `plone/plone-backend` - Environment Variables Reference + +This reference document covers all environment variables available for the Plone backend [Docker](https://www.docker.com/) image. + +For usage instructions and examples, see {doc}`backend`. + + +## Main variables + +| Environment variable | Zope option | Default value | +| --- | --- | --- | +| `DEBUG_MODE` | `debug-mode` | `off` | +| `SECURITY_POLICY_IMPLEMENTATION` | `security-policy-implementation` | `C` | +| `VERBOSE_SECURITY` | `verbose-security` | `false` | +| `DEFAULT_ZPUBLISHER_ENCODING` | `default-zpublisher-encoding` | `utf-8` | +| `LISTEN_PORT` | (no equivalent) | `8080` | + +### Listen port + +By default, the Zope process inside the container will listen on TCP port 8080. +In certain circumstances — Kubernetes or Podman pods — there may be a need to run +more than one Zope process within the network namespace, which would result in +listen port clashes as two different processes within the same namespace attempt +to listen to the same TCP port. + +In these cases, the variable `LISTEN_PORT` can be set to any particular port above +1024 to ensure that the container will listen on the desired port. + + +## Site creation variables + +| Environment variable | Description | +| --- | --- | +| `SITE` | Id of the site to be created, for example, `Plone` | +| `TYPE` | Type of the site, either `classic` or `volto`. Default: `volto` | +| `PROFILES` | Initialize site with additional profiles, for example, `eea.api.layout:default` | +| `DELETE_EXISTING` | Force site to be recreated if it already exists, for example, `true` | + + +## ZOPE variables + +| Environment variable | Description | Default value | +| --- | --- | --- | +| `ZODB_CACHE_SIZE` | database cache size | `50000` | + + +## ZEO variables + +| Environment variable | Description | ZEO option | Default value | +| --- | --- | --- | --- | +| `ZEO_ADDRESS` | URL of the ZEO interface, `host:port` | | | +| `ZEO_SHARED_BLOB_DIR` | ZEO option |`name` | `off` | +| `ZEO_READ_ONLY` | ZEO option |`read-only` | `false` | +| `ZEO_CLIENT_READ_ONLY_FALLBACK` | ZEO option |`read-only-fallback` | `false` | +| `ZEO_STORAGE` | ZEO option |`storage` | `1` | +| `ZEO_CLIENT_CACHE_SIZE` | ZEO option | `cache-size` | `128MB` | +| `ZEO_DROP_CACHE_RATHER_VERIFY` | ZEO option | `drop-cache-rather-verify` | `false` | + + +## Relational Database variables + +| Environment variable | Description | RelStorage option | Default value | +| --- | --- | --- | --- | +| `RELSTORAGE_DSN` | {ref}`containers-images-backend-postgresql-dsn-label` for the database interface | | | +| `RELSTORAGE_NAME` | RelStorage option | `name` | `storage` | +| `RELSTORAGE_READ_ONLY` | RelStorage option | `read-only` | `off` | +| `RELSTORAGE_KEEP_HISTORY` | RelStorage option | `keep-history` | `true` | +| `RELSTORAGE_COMMIT_LOCK_TIMEOUT` | RelStorage option | `commit-lock-timeout` | `30` | +| `RELSTORAGE_CREATE_SCHEMA` | RelStorage option | `create-schema` | `true` | +| `RELSTORAGE_SHARED_BLOB_DIR` | RelStorage option | `shared-blob-dir` | `false` | +| `RELSTORAGE_BLOB_CACHE_SIZE` | RelStorage option | `blob-cache-size` | `100mb` | +| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK` | RelStorage option | `blob-cache-size-check` | `10` | +| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK_EXTERNAL` | RelStorage option | `blob-cache-size-check-external` | `false` | +| `RELSTORAGE_BLOB_CHUNK_SIZE` | RelStorage option | `blob-chunk-size` | `1048576` | +| `RELSTORAGE_CACHE_LOCAL_MB` | RelStorage option | `cache-local-mb` | `10` | +| `RELSTORAGE_CACHE_LOCAL_OBJECT_MAX` | RelStorage option | `cache-local-object-max` | `16384` | +| `RELSTORAGE_CACHE_LOCAL_COMPRESSION` | RelStorage option | `cache-local-compression` | `none` | +| `RELSTORAGE_CACHE_DELTA_SIZE_LIMIT` | RelStorage option | `cache-delta-size-limit` | `100000` | + +```{note} +Currently this image supports only the configuration of a PostgreSQL backend via configuration variables. +If you need to use MySQL or Oracle, we recommend that you extend this image and overwrite the `/app/etc/relstorage.conf` file. +``` + +(containers-images-backend-postgresql-dsn-label)= + +### PostgreSQL DSN + +A valid PostgreSQL DSN is a list of parameters separated with whitespace. +A typical DSN looks like the following: + +```console +dbname='zodb' user='username' host='localhost' password='pass' +``` + + +## CORS variables + +| Environment variable | Description | Default value | +| --- | --- | --- | +| `CORS_ALLOW_ORIGIN` | Origins that are allowed access to the resource. Either a comma separated list of origins, for example `http://example.net,http://mydomain.com` or `*` | `http://localhost:3000,http://127.0.0.1:3000` | +| `CORS_ALLOW_METHODS` | A comma separated list of HTTP method names that are allowed by this CORS policy, for example `DELETE,GET,OPTIONS,PATCH,POST,PUT` | `DELETE,GET,OPTIONS,PATCH,POST,PUT` | +| `CORS_ALLOW_CREDENTIALS` | Indicates whether the resource supports user credentials in the request | `true` | +| `CORS_EXPOSE_HEADERS` | A comma separated list of response headers clients can access, for example `Content-Length,X-My-Header` | `Content-Length,X-My-Header` | +| `CORS_ALLOW_HEADERS` | A comma separated list of request headers allowed to be sent by the client, for example `X-My-Header` | `Accept,Authorization,Content-Type,X-Custom-Header` | +| `CORS_MAX_AGE` | Indicates how long the results of a preflight request can be cached | `3600` | + +These variables are used to configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS). + +(containers-images-backend-add-ons-label)= + +## Add-on variables + +| Environment variable | Description | Details | +| --- | --- | --- | +| `ADDONS` | A space separated list of python libraries to install | {ref}`containers-images-backend-add-ons-label` | +| `DEVELOP` | A space separated list of python libraries to install in editable mode | See {ref}`containers-images-backend-add-ons-label` | +| `PIP_PARAMS` | Parameters used in `pip` installation commands | [`pip install`](https://pip.pypa.io/en/stable/cli/pip_install/) | + diff --git a/docs/install/containers/images/backend.md b/docs/install/containers/images/backend.md index 762a2ea84..d84d6d2a9 100644 --- a/docs/install/containers/images/backend.md +++ b/docs/install/containers/images/backend.md @@ -11,6 +11,7 @@ myst: This chapter covers Plone backend [Docker](https://www.docker.com/) images using Python 3 and [pip](https://pip.pypa.io/en/stable/). +For a complete reference of all environment variables, see {doc}`backend-reference`. ## Using this image @@ -34,45 +35,7 @@ We encourage users of the `Plone` images to familiarize themselves with the opti [The Docker documentation](https://docs.docker.com/get-started/docker-concepts/running-containers/persisting-container-data/) is a good starting point for understanding the different storage options and variations. -## Configuration Variables - - -### Main variables - -| Environment variable | Zope option | Default value | -| --- | --- | --- | -| `DEBUG_MODE` | `debug-mode` | `off` | -| `SECURITY_POLICY_IMPLEMENTATION` | `security-policy-implementation` | `C` | -| `VERBOSE_SECURITY` | `verbose-security` | `false` | -| `DEFAULT_ZPUBLISHER_ENCODING` | `default-zpublisher-encoding` | `utf-8` | -| `LISTEN_PORT` | (no equivalent) | `8080` | - -#### Listen port - -By default, the Zope process inside the container will listen on TCP port 8080. -In certain circumstances — Kubernetes or Podman pods — there may be a need to run -more than one Zope process within the network namespace, which would result in -listen port clashes as two different processes within the same namespace attempt -to listen to the same TCP port. - -In these cases, the variable `LISTEN_PORT` can be set to any particular port above -1024 to ensure that the container will listen on the desired port. - -Plone 6 example: - -```shell -# Makes Zope listen to port 8081 instead of the default 8080. -docker run -p 8081:8081 -e LISTEN_PORT=8081 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} -``` - -### Site creation variables - -| Environment variable | Description | -| --- | --- | -| `SITE` | Id of the site to be created, for example, `Plone` | -| `TYPE` | Type of the site, either `classic` or `volto`. Default: `volto` | -| `PROFILES` | Initialize site with additional profiles, for example, `eea.api.layout:default` | -| `DELETE_EXISTING` | Force site to be recreated if it already exists, for example, `true` | +## Site creation It is possible to initialize your database with a Plone Site instance on its first run. To do so, pass the `SITE` environment variable with the name of the Plone Site instance, for example, `SITE=Plone`. @@ -81,6 +44,8 @@ If you want a Plone Classic UI instance, pass the environment variable and value To initialize it with additional profiles, pass them as space separated values via the `PROFILES` environment variable, for example, `PROFILES=eea.api.layout:default`. To recreate the Plone site when restarting the container, you can pass the `DELETE_EXISTING` environment variable. +For a complete reference of site creation variables, see {doc}`backend-reference`. + Plone 6 example: ```shell @@ -97,25 +62,10 @@ docker run -p 8080:8080 -e ADDONS="eea.facetednavigation" -e SITE="Plone" -e TYP We advise against using this feature on production environments. ``` -### ZOPE variables -| Environment variable | Description | Default value | -| --- | --- | --- | -| `ZODB_CACHE_SIZE` | database cache size | `50000` | - - -### ZEO variables - -| Environment variable | Description | ZEO option | Default value | -| --- | --- | --- | --- | -| `ZEO_ADDRESS` | URL of the ZEO interface, `host:port` | | | -| `ZEO_SHARED_BLOB_DIR` | ZEO option |`name` | `off` | -| `ZEO_READ_ONLY` | ZEO option |`read-only` | `false` | -| `ZEO_CLIENT_READ_ONLY_FALLBACK` | ZEO option |`read-only-fallback` | `false` | -| `ZEO_STORAGE` | ZEO option |`storage` | `1` | -| `ZEO_CLIENT_CACHE_SIZE` | ZEO option | `cache-size` | `128MB` | -| `ZEO_DROP_CACHE_RATHER_VERIFY` | ZEO option | `drop-cache-rather-verify` | `false` | +## Using ZEO +For a complete reference of ZEO environment variables, see {doc}`backend-reference`. #### Example @@ -146,36 +96,11 @@ volumes: ``` -### Relational Database variables +## Using Relational Database -| Environment variable | Description | RelStorage option | Default value | -| --- | --- | --- | --- | -| `RELSTORAGE_DSN` | {ref}`containers-images-backend-postgresql-dsn-label` for the database interface | | | -| `RELSTORAGE_NAME` | RelStorage option | `name` | `storage` | -| `RELSTORAGE_READ_ONLY` | RelStorage option | `read-only` | `off` | -| `RELSTORAGE_KEEP_HISTORY` | RelStorage option | `keep-history` | `true` | -| `RELSTORAGE_COMMIT_LOCK_TIMEOUT` | RelStorage option | `commit-lock-timeout` | `30` | -| `RELSTORAGE_CREATE_SCHEMA` | RelStorage option | `create-schema` | `true` | -| `RELSTORAGE_SHARED_BLOB_DIR` | RelStorage option | `shared-blob-dir` | `false` | -| `RELSTORAGE_BLOB_CACHE_SIZE` | RelStorage option | `blob-cache-size` | `100mb` | -| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK` | RelStorage option | `blob-cache-size-check` | `10` | -| `RELSTORAGE_BLOB_CACHE_SIZE_CHECK_EXTERNAL` | RelStorage option | `blob-cache-size-check-external` | `false` | -| `RELSTORAGE_BLOB_CHUNK_SIZE` | RelStorage option | `blob-chunk-size` | `1048576` | -| `RELSTORAGE_CACHE_LOCAL_MB` | RelStorage option | `cache-local-mb` | `10` | -| `RELSTORAGE_CACHE_LOCAL_OBJECT_MAX` | RelStorage option | `cache-local-object-max` | `16384` | -| `RELSTORAGE_CACHE_LOCAL_COMPRESSION` | RelStorage option | `cache-local-compression` | `none` | -| `RELSTORAGE_CACHE_DELTA_SIZE_LIMIT` | RelStorage option | `cache-delta-size-limit` | `100000` | +For a complete reference of Relational Database environment variables, see {doc}`backend-reference`. - -```{note} -Currently this image supports only the configuration of a PostgreSQL backend via configuration variables. -If you need to use MySQL or Oracle, we recommend that you extend this image and overwrite the `/app/etc/relstorage.conf` file. -``` - - -(containers-images-backend-postgresql-dsn-label)= - -#### PostgreSQL DSN +### PostgreSQL DSN A valid PostgreSQL DSN is a list of parameters separated with whitespace. A typical DSN looks like the following: @@ -184,8 +109,7 @@ A typical DSN looks like the following: dbname='zodb' user='username' host='localhost' password='pass' ``` - -#### Example +### Example ```yaml version: "3" @@ -210,20 +134,19 @@ services: - "5432:5432" ``` +```{note} +Currently this image supports only the configuration of a PostgreSQL backend via configuration variables. +If you need to use MySQL or Oracle, we recommend that you extend this image and overwrite the `/app/etc/relstorage.conf` file. +``` -### CORS variables -| Environment variable | Description | Default value | -| --- | --- | --- | -| `CORS_ALLOW_ORIGIN` | Origins that are allowed access to the resource. Either a comma separated list of origins, for example `http://example.net,http://mydomain.com` or `*` | `http://localhost:3000,http://127.0.0.1:3000` | -| `CORS_ALLOW_METHODS` | A comma separated list of HTTP method names that are allowed by this CORS policy, for example `DELETE,GET,OPTIONS,PATCH,POST,PUT` | `DELETE,GET,OPTIONS,PATCH,POST,PUT` | -| `CORS_ALLOW_CREDENTIALS` | Indicates whether the resource supports user credentials in the request | `true` | -| `CORS_EXPOSE_HEADERS` | A comma separated list of response headers clients can access, for example `Content-Length,X-My-Header` | `Content-Length,X-My-Header` | -| `CORS_ALLOW_HEADERS` | A comma separated list of request headers allowed to be sent by the client, for example `X-My-Header` | `Accept,Authorization,Content-Type,X-Custom-Header` | -| `CORS_MAX_AGE` | Indicates how long the results of a preflight request can be cached | `3600` | +## CORS configuration These variables are used to configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS). +For a complete reference of CORS environment variables, see {doc}`backend-reference`. + + (containers-images-backend-add-ons-label)= ### Add-ons @@ -253,13 +176,7 @@ This approach also allows you to test Plone with a specific version of one of it docker run -p 8080:8080 -e ADDONS="plone.volto==3.1.0a3" plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} start ``` -#### Add-on variables - -| Environment variable | Description | Details | -| --- | --- | --- | -| `ADDONS` | A space separated list of python libraries to install | {ref}`containers-images-backend-add-ons-label` | -| `DEVELOP` | A space separated list of python libraries to install in editable mode | {ref}`containers-images-backend-developing-packages-label` | -| `PIP_PARAMS` | Parameters used in `pip` installation commands | [`pip install`](https://pip.pypa.io/en/stable/cli/pip_install/) | +For a complete reference of add-on environment variables, see {doc}`backend-reference`. #### Adding configuration to `zope.conf` or additional ZCML @@ -272,9 +189,8 @@ method. However, you can derive your own container image, and drop in configuration fragments. See {ref}`backend-extending-from-this-image-label` below for instructions. -(containers-images-backend-developing-packages-label)= -### Developing packages variable +### Developing packages It is possible to install local packages instead of packages from pip. To do so, pass the `DEVELOP` environment variable with a space separated list of paths to Python packages to be installed. @@ -295,6 +211,8 @@ This approach also allows you to develop local packages by using a volume. docker run -p 8080:8080 -e DEVELOP="/app/src/mysite.policy" -v /path/to/mysite.policy:/app/src/mysite.policy plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} start ``` +For a complete reference of developing packages variables, see {doc}`backend-reference`. + (backend-extending-from-this-image-label)= ## Extending from this image diff --git a/docs/install/containers/images/frontend-reference.md b/docs/install/containers/images/frontend-reference.md new file mode 100644 index 000000000..307e321a0 --- /dev/null +++ b/docs/install/containers/images/frontend-reference.md @@ -0,0 +1,28 @@ +--- +myst: + html_meta: + "description": "Reference for plone/plone-frontend image environment variables" + "property=og:description": "Reference for plone/plone-frontend image environment variables" + "property=og:title": "Plone Frontend image - Environment Variables Reference" + "keywords": "Plone 6, install, installation, docker, containers, plone/plone-frontend, reference, environment variables" +--- + +# `plone/plone-frontend` - Environment Variables Reference + +This reference document covers all environment variables available for the Plone frontend [Docker](https://www.docker.com/) image. + +For usage instructions and examples, see {doc}`frontend`. + + +## Main variables + +| Environment variable | Description | Example | +| --- | --- | --- | +| `RAZZLE_API_PATH` | Used to generate frontend calls to the backend. Needs to be a public URL accessible by client browser. | `http://api.site.org/++api++/` | +| `RAZZLE_INTERNAL_API_PATH` | Used by the middleware to construct requests to the backend. It can be a non-public address. | `http://backend:8080/Plone` | +| `VOLTO_ROBOTSTXT` | Override the `robots.txt` file. | `"User-agent: *\nDisallow: "` | + +```{note} +For an extensive list of environment variables used by the frontend, visit {doc}`/volto/configuration/environmentvariables`. +``` + diff --git a/docs/install/containers/images/frontend.md b/docs/install/containers/images/frontend.md index a28dace1d..6e732a12a 100644 --- a/docs/install/containers/images/frontend.md +++ b/docs/install/containers/images/frontend.md @@ -14,22 +14,7 @@ The frontend is written using React and requires a Plone backend to be running a This image is **not a base image** to be extended in your projects, but an example of the Plone user experience out of the box. - -## Configuration Variables - - -### Main variables - - -| Environment variable | Description | Example | -| --- | --- | --- | -| `RAZZLE_API_PATH` | Used to generate frontend calls to the backend. Needs to be a public URL accessible by client browser. | `http://api.site.org/++api++/` | -| `RAZZLE_INTERNAL_API_PATH` | Used by the middleware to construct requests to the backend. It can be a non-public address. | `http://backend:8080/Plone` | -| `VOLTO_ROBOTSTXT` | Override the `robots.txt` file. | `"User-agent: *\nDisallow: "` | - -```{note} -For an extensive list of environment variables used by the frontend, visit {doc}`/volto/configuration/environmentvariables`. -``` +For a complete reference of all environment variables, see {doc}`frontend-reference`. ## Using as an example for your Volto project diff --git a/docs/install/containers/images/index.md b/docs/install/containers/images/index.md index c230db378..70cf4b969 100644 --- a/docs/install/containers/images/index.md +++ b/docs/install/containers/images/index.md @@ -22,6 +22,9 @@ The Plone community maintains the following official images: :hidden: true backend +backend-reference frontend +frontend-reference zeo +zeo-reference ``` diff --git a/docs/install/containers/images/zeo-reference.md b/docs/install/containers/images/zeo-reference.md new file mode 100644 index 000000000..89f161451 --- /dev/null +++ b/docs/install/containers/images/zeo-reference.md @@ -0,0 +1,25 @@ +--- +myst: + html_meta: + "description": "Reference for plone/plone-zeo image environment variables" + "property=og:description": "Reference for plone/plone-zeo image environment variables" + "property=og:title": "Plone ZEO image - Environment Variables Reference" + "keywords": "Plone 6, install, installation, docker, containers, plone/plone-zeo, reference, environment variables" +--- + +# `plone/plone-zeo` - Environment Variables Reference + +This reference document covers all environment variables available for the ZEO Server [Docker](https://www.docker.com/) image. + +For usage instructions and examples, see {doc}`zeo`. + + +## Main variables + +| Environment variable | ZEO option | Default value | +| --- | --- | --- | +| `ZEO_PORT` | `address` | `8100` | +| `ZEO_READ_ONLY` | `read-only` | `false` | +| `ZEO_INVALIDATION_QUEUE_SIZE` | `invalidation-queue-size` | `100` | +| `ZEO_PACK_KEEP_OLD` | `pack-keep-old` | `true` | + diff --git a/docs/install/containers/images/zeo.md b/docs/install/containers/images/zeo.md index 27538ce26..5606ce1ac 100644 --- a/docs/install/containers/images/zeo.md +++ b/docs/install/containers/images/zeo.md @@ -9,7 +9,9 @@ myst: # `plone/plone-zeo` -A ZEO Server [Docker](https://www.docker.com/) image using Python 3 and [pip](https://pip.pypa.io/en/stable/). +This chapter covers how to use the ZEO Server [Docker](https://www.docker.com/) image using Python 3 and [pip](https://pip.pypa.io/en/stable/). + +For a complete reference of all environment variables, see {doc}`zeo-reference`. ## Using this image @@ -68,15 +70,7 @@ We encourage users of the `Plone` images to familiarize themselves with the opti ## Configuration - -### Main variables - -| Environment variable | ZEO option | Default value | -| --- | --- | --- | -| `ZEO_PORT` | `address` | `8100` | -| `ZEO_READ_ONLY` | `read-only` | `false` | -| `ZEO_INVALIDATION_QUEUE_SIZE` | `invalidation-queue-size` | `100` | -| `ZEO_PACK_KEEP_OLD` | `pack-keep-old` | `true` | +For a complete reference of all environment variables, see {doc}`zeo-reference`. In case you need to configure an option not present in the environment variables, we suggest you to create a new image based on the default one: diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index c7d01ff5c..d07956210 100644 --- a/docs/install/containers/index.md +++ b/docs/install/containers/index.md @@ -11,6 +11,8 @@ myst: # Containers +## Introduction + The Plone 6 images have all the system requirements, prerequisites, and Plone 6 already installed, except those requirements needed for running the container engine itself. Using containers is the easiest way to deploy Plone 6. @@ -32,76 +34,10 @@ The {doc}`examples/index` and {doc}`recipes/index` provide configuration for pro :maxdepth: 2 :hidden: +getting-started images/index examples/index recipes/index ``` -## Getting started - -```{note} -Although there are many container engine tools for developing, managing, and running containers, we will use {term}`Docker` in this documentation. -``` - - -(install-containers-index-system-requirements-label)= - -### System requirements - -The system requirements include those required by Docker itself. - -- [Linux](https://docs.docker.com/desktop/setup/install/linux/) -- [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) -- [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) - -Plone 6 itself requires memory and disk space in addition to those of Docker alone. -See its {ref}`create-project-cookieplone-hardware-requirements-label`. - - -### Install Docker - -Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/) for your operating system. - -Docker Desktop includes all Docker tools. -{term}`Docker Compose` is one of the Docker tools that will be used in much of this documentation. - - -### Start Plone - -First start the Plone Backend, naming it `plone6-backend` and creating a site with its default configuration, using the following command. - -```shell -docker run --name plone6-backend -e SITE=Plone -d -p 8080:8080 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} -``` - -Now start the Plone Frontend, linking it to the `plone6-backend`: - -```shell -docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest -``` - - -## Access your Plone site - -Point your browser to `http://localhost:3000` and you should see the new Plone site. - -```{note} -The default user is `admin` and the password is `admin`. -``` - - -## Shutdown and cleanup - -To stop and clean up the containers use the following commands. - -```shell -docker stop plone6-frontend && docker rm plone6-frontend -docker stop plone6-backend && docker rm plone6-backend -``` - - -## Next steps - -Get to know the [Official Images](images/index) maintained by the Plone community. - -Also see some [examples](examples/index) of how to use the Official Images to bootstrap your projects. +For step-by-step instructions on getting started with containers, see {doc}`getting-started`.