Merge pull request #888 from plone/deployment-updates

Deployment updates

docs/effective-volto/architecture/CORS.md

@@ -51,4 +51,4 @@ The default backend will live in `http://localhost:8080/Plone` and the frontend
 RAZZLE_DEV_PROXY_API_PATH=http://localhost:8080/mysite
 ```
 
-In production, you'll probably will be using Volto's Seamless mode, so you won't be defining any custom `API_PATH` but using `++api++` traversal, and reverse proxying it through your webserver.
+In production, you'll probably will be using Volto's Seamless mode, so you won't be defining any custom `API_PATH` but using `++api++` traversal, and reverse proxying it through your web server.

docs/effective-volto/architecture/bootstrap-volto.md

@@ -107,7 +107,7 @@ To install Docker desktop for Mac, here are the detailed instructions:
 2. Install the package as any other Mac software, if required, follow
    instructions from:
 
-    https://docs.docker.com/desktop/install/mac-install/
+    https://docs.docker.com/desktop/setup/install/mac-install/
 
 3. Check that docker is installed correctly, open a new terminal and type:
 

docs/effective-volto/deployment/seamlessmode.md

@@ -30,11 +30,11 @@ The first question, *"what is my domain name?"* can be answered by looking at th
 The second question is a lot harder to answer, there can be so many unknowns, so, instead, we have a few layers of conventions and configuration variables.
 
 - If you're running Volto for development, the Plone backend is exposed from the frontend (`localhost:3000`) via a "devproxy" that assumes that the Plone backend is at `http://localhost:8080/Plone`. You can override it with [`RAZZLE_DEV_PROXY_API_PATH`](https://github.com/plone/volto/blob/5eb332829956dbf0505283b176008c9364ccf2f9/src/config/index.js#L101).
-- If you're running in production, the Plone backend is assumed to be exposed at the same domain, but available via the special traversal path, the `++api++`. So you need to add aditional rewrite rules in your Apache or Nginx proxy server to directly redirect those requests to the Plone backend.
+- If you're running in production, the Plone backend is assumed to be exposed at the same domain, but available via the special traversal path, the `++api++`. So you need to add aditional rewrite rules in your Apache or nginx proxy server to directly redirect those requests to the Plone backend.
 - Before the `++api++` traverser was developed, we would configure the proxy server to serve Plone directly via a `/api` subpath and the `_vh_api` VirtualHostMonster suffix. Then we would configure Volto with the `RAZZLE_API_PATH` variable. This is still available and works.
 - If you want the Volto nodejs server to communicate directly with the Plone backend via the internal network (for example, when running a Docker stack), you can use the `RAZZLE_INTERNAL_API_PATH` setting to configure the address of the Plone backend.
 
-## Nginx example config for seamless mode deployments
+## nginx example config for seamless mode deployments
 
 ```nginx
 upstream backend {

docs/effective-volto/development/i18n.md

@@ -13,7 +13,7 @@ myst:
 
 Internationalization (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts.
 Volto uses the library [react-intl](https://www.npmjs.com/package/react-intl) to provide translations for any potential language.
-Anything you can read in the [official documentation of react-intl](https://formatjs.io/docs/react-intl/) also applies for Volto.
+Anything you can read in the [official documentation of react-intl](https://formatjs.github.io/docs/getting-started/installation) also applies for Volto.
 
 However this section teaches you about the most common use cases relating to i18n you probably will have when developing your {doc}`../addons` or contributing to the Volto core itself.
 
@@ -95,12 +95,12 @@ function HelloWorld(props) {
 
 The identifier `hello_world` is then commonly used between all the translations.
 There are also more features available such as using placeholders.
-See the docs for all features in the [FormattedMessage component](https://formatjs.io/docs/react-intl/components#formattedmessage).
+See the docs for all features in the [FormattedMessage component](https://formatjs.github.io/docs/react-intl/components/#formattedmessage).
 
 ### Translating Attributes
 
 As `FormatMessage` is only suitable for creating text within HTML elements, it cannot be used for translating individual attributes.
-But with the method [formatMessage](https://formatjs.io/docs/react-intl/api/#formatmessage) there exists another way to translate primitive strings.
+But with the method [`formatMessage()`](https://formatjs.github.io/docs/react-intl/api#formatmessage) there exists another way to translate primitive strings.
 
 This approach can be best explained with an example: Assume you have a component called `TeaserImage` which contains an image that has for accessibility reasons the `alt` attribute.
 
@@ -112,7 +112,7 @@ To translate the `alt` attribute, you have to do the following steps:
     import { defineMessages, injectIntl, intlShape } from 'react-intl';
     ```
 
-2. Define a message (or more) via [defineMessages](https://formatjs.io/docs/react-intl/api/#definemessagesdefinemessage):
+2. Define a message (or more) via [`defineMessages()`](https://formatjs.github.io/docs/react-intl/api#definemessagesdefinemessage):
 
     ```js
     const messages = defineMessages({

docs/glossary.md

@@ -274,7 +274,14 @@ mxdev
 plonecli
     A Plone CLI for creating Plone packages. [plonecli usage](https://github.com/plone/plonecli)
 
+Cookiecutter
+    A command-line utility that creates projects from cookiecutters (project templates), for example, creating a Python package project from a Python package project template.
+    [See Cookiecutter's documentation](https://cookiecutter.readthedocs.io/en/stable/).
+
 Cookieplone
+    ```{versionadded} Volto 18.0.0-alpha.43
+    ```
+
     [Cookieplone](https://github.com/plone/cookieplone) is the method to create a Plone project.
     You can use Cookieplone to build a backend add-on, a new Volto add-on, or a full project with both backend and frontend.
     Cookieplone simplifies the process using robust Cookiecutter templates from {term}`cookieplone-templates`.
@@ -290,19 +297,13 @@ cookiecutter-plone-starter
     [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) is a `cookiecutter` template, created by the Plone community, to bootstrap
     a new Plone 6 project using Volto and a relational database.
 
-Cookiecutter
-    [Cookiecutter](https://github.com/cookiecutter/cookiecutter) is tool used to generate codebases / projects.
-
-cookieplone
-    [cookieplone](https://github.com/plone/cookieplone) is a wrapper around {term}`Cookiecutter` designed to streamline the development of Plone codebases
-
 Traefik
     [Traefik](https://doc.traefik.io/traefik/) is an open-source reverse proxy and load balancer designed to handle HTTP and TCP applications.
     It simplifies the deployment and routing of services and is particularly well-suited for cloud-native and containerized environments,
     offering features like automatic service discovery, middleware plugins, and robust security options.
 
-Nginx
-    [Nginx](https://nginx.org/en/) is a high-performance web server, reverse proxy, and load balancer that is known for its speed, reliability, and flexibility.
+nginx
+    [nginx](https://nginx.org/en/) is a high-performance web server, reverse proxy, and load balancer that is known for its speed, reliability, and flexibility.
     It can also serve as a mail proxy server and provides features for HTTP and TCP/UDP applications, making it a popular choice for serving web content,
     optimizing resource utilization, and enhancing web performance and security.
 

docs/mastering-plone/volto_testing.md

@@ -151,7 +151,7 @@ exports[`renders a talk view component with only required props 1`] = `
 ```
 
 ```{seealso}
-{doc}`plone6docs:volto/contributing/testing` in docs.plone.org.
+{doc}`plone6docs:volto/contributing/testing`
 ```
 
 (testing-cypress)=

docs/plone-deployment/deploy.md

@@ -36,7 +36,7 @@ make test
 
 ## Manual Deployment with `devops/Makefile`
 
-Utilize the `Makefile` at {file}`devops/Makefile` for manual deployment.
+Utilize the {file}`Makefile` at {file}`devops/Makefile` for manual deployment.
 
 ### Deploying the Stack
 
@@ -66,9 +66,9 @@ make stack-create-site
 
 Monitor the logs of each service with these commands:
 
-- Traefik: ```make logs-webserver```
-- Frontend: ```make logs-frontend```
-- Backend: ```make logs-backend```
+-   Traefik: `make logs-webserver`
+-   Frontend: `make logs-frontend`
+-   Backend: `make logs-backend`
 
 ## Automating Deployment with GitHub Actions
 
@@ -88,17 +88,17 @@ Monitor the logs of each service with these commands:
 
 Add secrets in the `Secrets` section of your environment. Refer to the table below:
 
-| Secret Name | Secret Value | Description |
-|-------------|--------------|-------------|
-| DEPLOY_HOST | Your hostname or IP | The Docker Swarm manager’s address. |
-| DEPLOY_PORT | 22 | The SSHD port. |
-| DEPLOY_USER | Your username | A user with Docker command permissions. |
-| DEPLOY_SSH  | Content of `devops/etc/keys/plone_prod_deploy_rsa` | The private SSH key for connection. |
-| ENV_FILE    | Content of {file}`devops/.env_file_gha` | File containing environment variables for the stack file. |
+| Secret Name | Secret Value                                             | Description                                               |
+|-------------|----------------------------------------------------------|-----------------------------------------------------------|
+| DEPLOY_HOST | Your hostname or IP                                      | The Docker Swarm manager's address.                       |
+| DEPLOY_PORT | 22                                                       | The SSHD port.                                            |
+| DEPLOY_USER | Your username                                            | A user with Docker command permissions.                   |
+| DEPLOY_SSH  | Content of {file}`devops/etc/keys/plone_prod_deploy_rsa` | The private SSH key for connection.                       |
+| ENV_FILE    | Content of {file}`devops/.env_file_gha`                  | File containing environment variables for the stack file. |
 
 #### Adding Repository Variables
 
-Navigate to `Settings` > `Secrets and Variables` > `Actions`. Under `Variables`, add the repository variable:
+Navigate to {menuselection}`Settings --> Secrets and Variables --> Actions`. Under {guilabel}`Variables`, add the repository variable:
 
 | Name     | Value |
 |----------|-------|
@@ -111,15 +111,15 @@ This variable is referenced in {file}`.github/workflows/manual_deploy.yml`.
 Ensure both Backend and Frontend tests are successful and images for both servers are available.
 
 1. Go to the project's repository on GitHub.
-2. Click the `Actions` tab.
-3. Find **Manual Deployment...** and click `Run workflow`.
-4. Select `Branch: main` under **Use workflow from**.
-5. Press `Run workflow`.
+2. Click the {guilabel}`Actions` tab.
+3. Find {guilabel}`Manual Deployment...` and click {guilabel}`Run workflow`.
+4. Select {guilabel}`Branch: main` under {guilabel}`Use workflow from`.
+5. Press {guilabel}`Run workflow`.
 
-The workflow connects to **DEPLOY_HOST** using **DEPLOY_USER** and **DEPLOY_SSH** key, initiates a new deployment using the specified stack, and provides a detailed deployment report.
+The workflow connects to `DEPLOY_HOST` using `DEPLOY_USER` and `DEPLOY_SSH` key, initiates a new deployment using the specified stack, and provides a detailed deployment report.
 
 ## Accessing the Site
 
 Your site should now be accessible via the defined public URL.
 
-Note: Ensure to replace placeholders like `<url>` with actual values as per your project's specifics. Also, ensure that the paths to files and directories are correct and exist in your project structure.
+Note: Ensure you replace placeholders, such as `<url>`, with actual values per your project's specifics. Also, ensure that the paths to files and directories are correct and exist in your project structure.

docs/plone-deployment/index.md

@@ -38,4 +38,5 @@ project-start
 project-edit
 server-setup
 deploy
+virtual-host
 ```

docs/plone-deployment/intro.md

@@ -28,6 +28,8 @@ or considering a virtual machine on your personal computer for testing, this tra
 
 We will delve into a basic setup, scalable to accommodate extensive Plone installations.
 
+(deployment-training-choices)=
+
 ### Training Choices
 
 #### Linux
@@ -55,9 +57,9 @@ simplifies the setup process, making it accessible even for beginners.
 
 #### GitHub and GitHub Actions
 
-With Plone’s development anchored on GitHub, the community is gravitating towards GitHub Actions for new packages.
+With Plone's development anchored on GitHub, the community is gravitating towards GitHub Actions for new packages.
 The principles outlined are adaptable to GitLab, Jenkins, and similar platforms.
 
 #### Kubernetes
 
-While the current training edition doesn’t cover Kubernetes, we anticipate its inclusion in upcoming updates.
+While the current training edition doesn't cover Kubernetes, we anticipate its inclusion in future updates.

docs/plone-deployment/plone-docker-images.md

@@ -9,16 +9,15 @@ myst:
 
 # Plone Docker Images
 
-Since the release of Plone 6, the community has a new set of Docker images -- and offering more base options.
+Since the release of Plone 6, the community has a new set of Docker images offering more base options.
 
-## plone/plone-frontend
+## `plone/plone-frontend`
 
-Repository available at [https://github.com/plone/plone-frontend/](https://github.com/plone/plone-frontend/)
+Repository available at https://github.com/plone/plone-frontend/.
 
-Installs the Plone 6 default user-experience (Using the React-powered frontend: Volto).
+Installs the Plone 6 user-experience using the React-powered frontend, Volto.
 
-Should be used to showcase the default Plone 6 experience, as new projects will probably implement their own Docker images (with a similar Dockerfile),
-like the one below:
+Should be used to showcase the Plone 6 experience, as new projects will probably implement their own Docker images (with a similar Dockerfile), like the one below:
 
 ```Dockerfile
 # syntax=docker/dockerfile:1
@@ -55,9 +54,9 @@ RUN <<EOT
 EOT
 ```
 
-## plone/plone-backend
+## `plone/plone-backend`
 
-Repository available at [https://github.com/plone/plone-backend/](https://github.com/plone/plone-backend/)
+Repository available at https://github.com/plone/plone-backend/.
 
 Installs the Plone 6 backend using a pip-based installation.
 This approach makes it easier and faster to extend this image in your own project.
@@ -107,8 +106,8 @@ RUN <<EOT
 EOT
 ```
 
-## plone/plone-zeo
+## `plone/plone-zeo`
 
-Repository available at [https://github.com/plone/plone-zeo/](https://github.com/plone/plone-zeo/)
+Repository available at https://github.com/plone/plone-zeo/.
 
 Installs a ZEO database server.

docs/plone-deployment/plone-stack.md

@@ -10,27 +10,27 @@ myst:
 
 Explore the intricate components of the Plone stack, tailored for deploying a modern Plone 6 site with a ReactJS-powered frontend.
 For deployments focusing on Plone Classic UI with server-side HTML rendering, the frontend component is excluded.
-This guide won’t cover the integration of a web accelerator or the setup of an edge caching service.
+This guide won't cover the integration of a web accelerator or the setup of an edge caching service.
 
 ## Components of the Plone Stack
 
-### Webserver
+### Web server
 
-The webserver, accessible externally on ports 80 and 443, handles the routing and rewriting of HTTP requests to the Plone frontend and backend, and is tasked with TLS termination. While {term}`Nginx` and {term}`Traefik` are recommended, other webservers can also be employed. This training will exclusively utilize Traefik.
+The web server, accessible externally on ports 80 and 443, handles the routing and rewriting of HTTP requests to the Plone frontend and backend, and is tasked with TLS termination. While {term}`nginx` and {term}`Traefik` are recommended, other web servers can also be employed. This training will exclusively utilize Traefik.
 
-To understand the rewrite rules used in Traefik, please read our reference about {term}`Zope`'s [Virtual Hosting Services](./virtual_host).
+To understand the rewrite rules used in Traefik, please read our reference about {term}`Zope`'s {doc}`virtual-host`.
 
 ### Web Accelerator
 
-{term}`Varnish`, a web accelerator, is positioned between the external webserver and internal services to cache dynamically generated content. For a detailed Plone setup with Varnish, refer to the [volto-caching](https://github.com/collective/volto-caching) repository.
+{term}`Varnish`, a web accelerator, is positioned between the external web server and internal services to cache dynamically generated content. For a detailed Plone setup with Varnish, refer to the [volto-caching](https://github.com/collective/volto-caching) repository.
 
 ### Plone Frontend
 
-Hosted on a Node HTTP-server running on port 3000, the Plone frontend constitutes the default user interface and requires access to the Plone Backend and the webserver.
+Hosted on a Node.js HTTP-server running on port 3000, the Plone frontend constitutes the default user interface and requires access to the Plone Backend and the web server.
 
 ### Plone Backend
 
-Operating on port 8080, the Plone Backend, a WSGI process, serves as the HTTP server hosting the Plone API. It’s optimal to pair it with a specialized database like ZEO server or a relational database via RelStorage, supporting PostgreSQL, MySQL/MariaDB, and Oracle. A separate shared file system is essential for storing binary data if ZEO is employed.
+Operating on port 8080, the Plone Backend, a WSGI process, serves as the HTTP server hosting the Plone API. It's optimal to pair it with a specialized database like ZEO server or a relational database via RelStorage, supporting PostgreSQL, MySQL/MariaDB, and Oracle. A separate shared file system is essential for storing binary data if ZEO is employed.
 
 ### Database
 
@@ -43,7 +43,7 @@ The database layer can range from a simple ZODB with file storage to more scalab
 #### Without Specialized Database
 
 ```
-Webserver -> Plone Frontend -> Plone Backend (file storage).
+Web server → Plone Frontend → Plone Backend (file storage)
 ```
 
 ```{note}
@@ -53,7 +53,7 @@ Ideal for demo sites and Plone trials.
 #### With Specialized Database
 
 ```
-Webserver → Plone Frontend → Plone Backend → Database
+Web server → Plone Frontend → Plone Backend → Database
 ```
 
 ```{note}
@@ -63,22 +63,22 @@ Solution to be presented in this training.
 #### With Specialized Database and Caching
 
 ```
-Webserver → Web Accelerator → Plone Frontend → Plone Backend → Database
+Web server → Web Accelerator → Plone Frontend → Plone Backend → Database
 ```
 
 ### Multi-server Setup
 
 In a multi-server environment, load distribution and redundancy are achieved through various configurations, enabling horizontal scaling.
 
 ```{figure} _static/request_flow.png
-:alt: Flow of a request to https://example.com
+:alt: Flow of a request to `https://example.com`
 
 Flow of a request to https://example.com
 ```
 
-#### Webserver and Web Accelerator Layer
+#### Web server and Web Accelerator Layer
 
-Externally accessible machine hosting both the webserver and web accelerator on ports 80 and 443.
+Externally accessible machine hosting both the web server and web accelerator on ports 80 and 443.
 
 #### Plone Application Layer (Frontend and Backend)