From 8a8e10eb6b2d2ab16a3c1f66d7b8cd1ba86c7e6b Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 00:14:52 -0800
Subject: [PATCH 01/11] Copy terms from Documentation
---
docs/glossary.md | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/docs/glossary.md b/docs/glossary.md
index 92b1e9775..49ef23000 100644
--- a/docs/glossary.md
+++ b/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,12 +297,6 @@ 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,
From 04cf05cc5cc4e63151b1e3161373c5fd0e63e234 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 00:20:06 -0800
Subject: [PATCH 02/11] Use a definition list for terms Remove bold from
headings since they are already bold Troubleshooting is not a prerequisite,
increase its and its children's heading level
---
docs/plone-deployment/intro.md | 2 +-
docs/plone-deployment/setup.md | 31 +++++++++++++++++--------------
2 files changed, 18 insertions(+), 15 deletions(-)
diff --git a/docs/plone-deployment/intro.md b/docs/plone-deployment/intro.md
index 7e0c3d603..b839b6197 100644
--- a/docs/plone-deployment/intro.md
+++ b/docs/plone-deployment/intro.md
@@ -60,4 +60,4 @@ 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.
diff --git a/docs/plone-deployment/setup.md b/docs/plone-deployment/setup.md
index b874564f9..dc059850b 100644
--- a/docs/plone-deployment/setup.md
+++ b/docs/plone-deployment/setup.md
@@ -11,18 +11,21 @@ myst:
Ensure a seamless learning experience by preparing your computer with the necessary software before the training commences.
-## Pre-requisites
+## Prerequisites
-### 1. **Operating System**
+### 1. Operating System
-- **Linux/macOS:** A recent version is preferred. macOS users should have [Homebrew](https://brew.sh/) installed.
-- **Windows:** Consider using [WSL2 with Ubuntu](https://documentation.ubuntu.com/wsl/en/latest/), though it’s not officially tested for this training.
+Linux/macOS
+: A recent version is preferred. macOS users should have [Homebrew](https://brew.sh/) installed.
-### 2. **Code Editor**
+Windows
+: Consider using [WSL2 with Ubuntu](https://documentation.ubuntu.com/wsl/en/latest/), though it’s not officially tested for this training.
+
+### 2. Code Editor
Choose a code editor you’re comfortable with, such as VSCode, PyCharm, Sublime, VI, or Emacs.
-### 3. **Python**
+### 3. Python
Install Python version 3.11.x or 3.12.x, ensuring that `pip` is included and updated.
@@ -40,7 +43,7 @@ python -m pip install --upgrade pipx uv
Use [Pyenv](https://github.com/pyenv/pyenv) if your system doesn’t provide the required Python version.
```
-### 4. **Docker**
+### 4. Docker
Ensure Docker version 27.2.0 or above is installed. Verify with:
@@ -54,7 +57,7 @@ Ensure Docker is running. Verify with:
docker ps
```
-### 5. **Node and Node Tools**
+### 5. Node and Node Tools
Install the latest Node LTS version using [NVM](https://github.com/nvm-sh/nvm/blob/master/README.md).
@@ -79,7 +82,7 @@ nvm use
```
````
-### 6. **External Services**
+### 6. External Services
#### GitHub Account
@@ -97,17 +100,17 @@ We'll use the GitHub Container Registry during the training. The concepts are al
docker login
```
-### 7. **Cookieplone**
+### 7. Cookieplone
The latest version of {term}`Cookieplone` will be used, and it doesn’t require a separate installation as we’ll use `pipx`.
-### 8. **Make**
+### 8. Make
{term}`Make` is pre-installed on most Linux distributions. For macOS, install Xcode and its command-line tools. Windows users are advised to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) that includes `make`.
-### 9. **Troubleshooting**
+## Troubleshooting
-#### Insufficient Docker virtual disk space
+### Insufficient Docker virtual disk space
Docker requires sufficient virtual disk space to install and build images. A typical error message may be: `Could not create directory.` or anything else that mentions writing to the image.
To resolve this, use an appropriate docker system prune option, such as:
@@ -129,6 +132,6 @@ Under {guilabel}`Prefences > Resources > Advanced`, you can configure appropriat
- [Change Docker Desktop settings on Linux](https://docs.docker.com/desktop/settings/#advanced)
```
-#### Insufficient Docker virtual memory
+### Insufficient Docker virtual memory
Docker requires sufficient memory to install and build images. See the previous item for details.
From 407496bd36c7afd616c731fe43dbcf20d99b10fd Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 00:41:43 -0800
Subject: [PATCH 03/11] Use straight quotes. Backtick inline literals. Rename _
to - in virtual-host, and add to index and refactor. Clean up MyST markup for
virtual-host.md
---
docs/plone-deployment/deploy.md | 2 +-
docs/plone-deployment/index.md | 1 +
docs/plone-deployment/intro.md | 4 +-
docs/plone-deployment/plone-stack.md | 6 +-
docs/plone-deployment/project-edit.md | 8 +-
docs/plone-deployment/project-start.md | 4 +-
docs/plone-deployment/server-setup.md | 6 +-
docs/plone-deployment/setup.md | 8 +-
docs/plone-deployment/virtual-host.md | 123 +++++++++++++++++++++++++
docs/plone-deployment/virtual_host.md | 122 ------------------------
10 files changed, 143 insertions(+), 141 deletions(-)
create mode 100644 docs/plone-deployment/virtual-host.md
delete mode 100644 docs/plone-deployment/virtual_host.md
diff --git a/docs/plone-deployment/deploy.md b/docs/plone-deployment/deploy.md
index ded00f687..8500a1e2d 100644
--- a/docs/plone-deployment/deploy.md
+++ b/docs/plone-deployment/deploy.md
@@ -90,7 +90,7 @@ Add secrets in the `Secrets` section of your environment. Refer to the table bel
| Secret Name | Secret Value | Description |
|-------------|--------------|-------------|
-| DEPLOY_HOST | Your hostname or IP | The Docker Swarm manager’s address. |
+| 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. |
diff --git a/docs/plone-deployment/index.md b/docs/plone-deployment/index.md
index b87e5d3bd..e006576e8 100644
--- a/docs/plone-deployment/index.md
+++ b/docs/plone-deployment/index.md
@@ -38,4 +38,5 @@ project-start
project-edit
server-setup
deploy
+virtual-host
```
diff --git a/docs/plone-deployment/intro.md b/docs/plone-deployment/intro.md
index b839b6197..cd36e75d4 100644
--- a/docs/plone-deployment/intro.md
+++ b/docs/plone-deployment/intro.md
@@ -55,9 +55,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 future updates.
+While the current training edition doesn't cover Kubernetes, we anticipate its inclusion in future updates.
diff --git a/docs/plone-deployment/plone-stack.md b/docs/plone-deployment/plone-stack.md
index 9190d3b72..9cd9a153d 100644
--- a/docs/plone-deployment/plone-stack.md
+++ b/docs/plone-deployment/plone-stack.md
@@ -10,7 +10,7 @@ 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
@@ -18,7 +18,7 @@ This guide won’t cover the integration of a web accelerator or the setup of an
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.
-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
@@ -30,7 +30,7 @@ Hosted on a Node HTTP-server running on port 3000, the Plone frontend constitute
### 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
diff --git a/docs/plone-deployment/project-edit.md b/docs/plone-deployment/project-edit.md
index dc98fb7eb..e16da8914 100644
--- a/docs/plone-deployment/project-edit.md
+++ b/docs/plone-deployment/project-edit.md
@@ -20,7 +20,7 @@ Both Plone Frontend and Backend in your project support add-on integration. Add-
### Adding a New Block to the Frontend
-We’ll illustrate the process of integrating a Frontend add-on, `@plonegovbr/volto-code-block`, which renders highlighted source code blocks. We’ll centralize all modifications within our project's add-on, `volto-ploneconf2024`, to streamline future Volto version upgrades.
+We'll illustrate the process of integrating a Frontend add-on, `@plonegovbr/volto-code-block`, which renders highlighted source code blocks. We'll centralize all modifications within our project's add-on, `volto-ploneconf2024`, to streamline future Volto version upgrades.
#### Incorporating a New Dependency
@@ -59,7 +59,7 @@ git push
## Implementing OAuth Support with GitHub
-We’ll now add GitHub OAuth authentication, involving both Backend and Frontend add-ons and GitHub OAuth application creation.
+We'll now add GitHub OAuth authentication, involving both Backend and Frontend add-ons and GitHub OAuth application creation.
### Creating a GitHub OAuth Application
@@ -88,7 +88,7 @@ To ensure the name `ploneconf24.localhost` points to the address `127.0.0.1`, we
1. Open the Start Menu and search for **Notepad**.
Right-click on it and choose **Run as administrator**.
If Windows asks if you want the application to make changes to the system, click **Yes**.
- (If you don’t open Notepad as an administrator, you won’t be able to modify the `hosts` file.)
+ (If you don't open Notepad as an administrator, you won't be able to modify the `hosts` file.)
2. In Notepad, click **File » Open**.
Then navigate to the following folder:
@@ -114,7 +114,7 @@ ping ploneconf24.localhost
Start the Docker Compose stack with `make stack-start`. Navigate to [http://ploneconf2024.localhost/ClassicUI/login](http://ploneconf2024.localhost/ClassicUI/login) and authenticate.
-Install `pas.plugins.authomatic` from the {guilabel}`Add-ons` control panel and configure it with the following JSON configuration, replacing `KEYHERE` and `SECRETHERE` with your GitHub OAuth application’s client ID and secret.
+Install `pas.plugins.authomatic` from the {guilabel}`Add-ons` control panel and configure it with the following JSON configuration, replacing `KEYHERE` and `SECRETHERE` with your GitHub OAuth application's client ID and secret.
```json
{
diff --git a/docs/plone-deployment/project-start.md b/docs/plone-deployment/project-start.md
index 55141dceb..4381fb76c 100644
--- a/docs/plone-deployment/project-start.md
+++ b/docs/plone-deployment/project-start.md
@@ -88,7 +88,7 @@ Docker will download necessary images, build Frontend and Backend images, and in
### Checking the Stack Status
-Verify the stack’s operational status with:
+Verify the stack's operational status with:
```shell
make stack-status
@@ -118,7 +118,7 @@ Accessing the site at http://ploneconf2024.localhost
### Updating the Codebase
-For codebase modifications, re-run `make stack-start` to rebuild the affected containers, ensuring your site’s behavior aligns with the updates.
+For codebase modifications, re-run `make stack-start` to rebuild the affected containers, ensuring your site's behavior aligns with the updates.
### Stopping the Stack
diff --git a/docs/plone-deployment/server-setup.md b/docs/plone-deployment/server-setup.md
index 4bddb9316..d9d24a3b0 100644
--- a/docs/plone-deployment/server-setup.md
+++ b/docs/plone-deployment/server-setup.md
@@ -27,7 +27,7 @@ Create a new {file}`.env` file by copying the content from the existing `.env_di
cp .env_dist .env
```
-Customize the {file}`.env` file to match your specific deployment environment. Here’s an example configuration:
+Customize the {file}`.env` file to match your specific deployment environment. Here's an example configuration:
```shell
DEPLOY_ENV=prod
@@ -83,7 +83,7 @@ ssh plone@ploneconf2024-<your-github-username>.tangrama.com.br
## Setting Up Docker
-Ensure you’re logged into Docker, as the deployment process uses public images. Create a new Docker context for the remote server:
+Ensure you're logged into Docker, as the deployment process uses public images. Create a new Docker context for the remote server:
```shell
make docker-setup
@@ -97,6 +97,6 @@ make docker-info
# Review
-By now you’ve now successfully set up a Plone deployment server using Ansible for automated provisioning, Docker for containerization, and Docker Swarm for scalability and availability.
+By now you've now successfully set up a Plone deployment server using Ansible for automated provisioning, Docker for containerization, and Docker Swarm for scalability and availability.
The next step is to deploy your project to this server.
diff --git a/docs/plone-deployment/setup.md b/docs/plone-deployment/setup.md
index dc059850b..f8d211214 100644
--- a/docs/plone-deployment/setup.md
+++ b/docs/plone-deployment/setup.md
@@ -19,11 +19,11 @@ Linux/macOS
: A recent version is preferred. macOS users should have [Homebrew](https://brew.sh/) installed.
Windows
-: Consider using [WSL2 with Ubuntu](https://documentation.ubuntu.com/wsl/en/latest/), though it’s not officially tested for this training.
+: Consider using [WSL2 with Ubuntu](https://documentation.ubuntu.com/wsl/en/latest/), though it's not officially tested for this training.
### 2. Code Editor
-Choose a code editor you’re comfortable with, such as VSCode, PyCharm, Sublime, VI, or Emacs.
+Choose a code editor you're comfortable with, such as VSCode, PyCharm, Sublime, VI, or Emacs.
### 3. Python
@@ -40,7 +40,7 @@ python -m pip install --upgrade pipx uv
```
```{tip}
-Use [Pyenv](https://github.com/pyenv/pyenv) if your system doesn’t provide the required Python version.
+Use [Pyenv](https://github.com/pyenv/pyenv) if your system doesn't provide the required Python version.
```
### 4. Docker
@@ -102,7 +102,7 @@ We'll use the GitHub Container Registry during the training. The concepts are al
### 7. Cookieplone
-The latest version of {term}`Cookieplone` will be used, and it doesn’t require a separate installation as we’ll use `pipx`.
+The latest version of {term}`Cookieplone` will be used, and it doesn't require a separate installation as we'll use `pipx`.
### 8. Make
diff --git a/docs/plone-deployment/virtual-host.md b/docs/plone-deployment/virtual-host.md
new file mode 100644
index 000000000..d19896bfb
--- /dev/null
+++ b/docs/plone-deployment/virtual-host.md
@@ -0,0 +1,123 @@
+---
+myst:
+ html_meta:
+ "description": "Virtual Hosting Services"
+ "property=og:description": "Understand how to use Zope infrastructure to rewrite URLs in run time."
+ "property=og:title": ""Virtual Hosting Services"
+ "keywords": "Plone, Deployment, Stack, Configuration, Guide, Virtual Host Monster, VHM"
+---
+
+# Virtual Hosting Services
+
+Zope comes with one object that helps you do virtual hosting: *Virtual Host Monster* (VHM). Virtual hosting is a way to serve many websites with one backend server.
+
+## Virtual Host Monster
+
+Zope objects need to generate their own URLs from time to time. For instance, when a Zope object has its "absolute_url" method called, it needs to return a URL which is appropriate for itself. This URL typically contains a hostname, a port, and a path. In a "default" Zope installation, this hostname, port, and path is typically what you want. But when it comes time to serve multiple websites out of a single Zope instance, each with their own "top-level" domain name, or when it comes time to integrate a Zope Folder within an existing website using Apache or another webserver, the URLs that Zope objects generate need to change to suit your configuration.
+
+A Virtual Host Monster's only job is to change the URLs which your Zope objects generate. This allows you to customize the URLs that are displayed within your Zope application, allowing an object to have a different URL when accessed in a different way. This is most typically useful, for example, when you wish to "publish" the contents of a single Zope Folder (e.g. `/FooFolder`) as a URL that does not actually contain this Folder's name (for example, as the hostname `www.foofolder.com`).
+
+The Virtual Host Monster performs this job by intercepting and deciphering information passed to Zope within special path elements encoded in the URLs of requests which come into Zope. If these special path elements are absent in the URLs of requests to the backend server, the Virtual Host Monster does nothing. If they are present, however, the Virtual Host Monster deciphers the information passed in via these path elements and causes your Zope objects to generate a URL that is different from their "default" URL.
+
+The Zope values which are affected by the presence of a Virtual Host Monster include `REQUEST` variables starting with `URL` or `BASE` (such as `URL1`, `BASE2`, or `URLPATH0`), and the `absolute_url()` methods of objects.
+
+Virtual Host Monster configuration can be complicated because it requires that you *rewrite* URLs "on the way in" to Zope. In order for the special path elements to be introduced into the URL of the request sent to Zope, a front-end URL "rewriting" tool needs to be employed. Virtual Host Monster comes with a simple rewriting tool in the form of its *Mappings* view, or alternately you can use Apache or another web server to rewrite URLs of requests destined to Zope for you.
+
+
+### Configuring the Virtual Host Monster
+
+The default mode for configuring the Virtual Host Monster is not to do any configuration at all! Rather, the external router or webserver modifies the request URL to signal what the *real* public URL for the request should be.
+
+If you *do* choose to change the settings of your VHM, the easiest method to do so is to use the VHM`s ZMI interface.
+
+### Special VHM Path Elements `VirtualHostBase` and `VirtualHostRoot`
+
+A Virtual Host Monster doesn't do anything unless it sees one of the following special path elements in a URL.
+
+#### `VirtualHostBase`
+
+If a Virtual Host Monster "sees" this name in the incoming URL, it causes {term}`Zope` objects to generate URLs with a potentially different protocol, a potentially different hostname, and a potentially different port number.
+
+#### `VirtualHostRoot`
+
+If a Virtual Host Monster "sees" this name in the incoming URL, it causes Zope objects to generate URLs that have a potentially different "path root."
+
+### `VirtualHostBase`
+
+The `VirtualHostBase` declaration is typically found at the beginning of an incoming URL. A Virtual Host Monster will intercept two path elements following this name and will use them to compose a new protocol, hostname, and port number.
+
+The two path elements which must follow a `VirtualHostBase` declaration are `protocol` and `hostname:portnumber`. They must be separated by a single slash. The colon and portnumber parts of the second element are optional, and if they don't exist, the Virtual Host Monster will not change the port number of Zope-generated URLs.
+
+Examples:
+
+- If a VHM is installed and a request comes into your server with the following URL.
+
+ `http://backend:8080/VirtualHostBase/http/example.com`
+
+ URLs generated by Zope objects will start with `http://example.com:8080`.
+
+- If a VHM is installed in the root folder, and a request comes into your server with the following URL.
+
+ `http://backend:8080/VirtualHostBase/http/example.com:80`
+
+ URLs generated by Zope objects will start with `http://example.com` (port 80 is the default port number, so it is left out).
+
+- If a VHM is installed in the root folder, and a request comes into your Zope with the following URL.
+
+ `http://backend:8080/VirtualHostBase/https/example.com:443`
+
+ URLs generated by Zope objects will start with `https://example.com/` (port 443 is the default https port number, so it is left off).
+
+One thing to note when reading the examples above is that if your Zope is running on a port number like 8080, and you want generated URLs to not include this port number and instead be served on the standard HTTP port (80), you must specifically include the default port 80 within the VirtualHostBase declaration, for exemple, `/VirtualHostBase/http/example.com:80`. If you don't specify the `:80`, your Zope's HTTP port number will be used (which is likely not what you want).
+
+### `VirtualHostRoot`
+
+The `VirtualHostRoot` declaration is typically found near the end of an incoming URL. A Virtual Host Monster will gather up all path elements that *precede* and *follow* the `VirtualHostRoot` name, traverse the Zope object hierarchy with these elements, and publish the object it finds with the path rewritten to the path element(s) that *follow* the `VirtualHostRoot` name.
+
+This is easier to understand by example. For a URL `/a/b/c/VirtualHostRoot/d`, the Virtual Host Monster will traverse `a/b/c/d` and then generate a URL with path `/d`.
+
+Examples:
+
+- If a VHM is installed in the root folder, and a request comes into your Zope with the following URL.
+
+ `http://backend:8080/Folder/VirtualHostRoot/`
+
+ The object `Folder` will be traversed to and published, and URLs generated by Zope will start with `http://backend:8080/`, and when they are visited, they will be considered relative to `Folder`.
+
+- If a VHM is installed in the root folder, and a request comes into your Zope with the following URL.
+
+ `http://backend:8080/HomeFolder/VirtualHostRoot/Chris`
+
+ The object `/Folder/Chris` will be traversed to and published, URLs generated by Zope will start with `http://backend:8080/Chris`, and when they are visited, they will be considered relative to `/HomeFolder/Chris`.
+
+### Using `VirtualHostRoot` and `VirtualHostBase` Together
+
+The most common sort of virtual hosting setup is one in which you create a Folder in your Zope root for each domain that you want to serve. For instance, the site `https://example.com` is served from a Plone Site in the Zope root named /Plone while the site `https://example.org` is served from another Plone Site in the Zope root named `/OrgSite`. In order to do this, you need to generate URLs that have both `VirtualHostBase` and `VirtualHostRoot` in them.
+
+To access `/OrgSite` as `https://example.org`, you would cause Zope to be visited via the following URL.
+
+`/VirtualHostBase/https://example.org/OrgSite/VirtualHostRoot/`
+
+In the same Zope instance, to access `/Plone` as `https://example.com/`, you would cause Zope to be visited via the following URL.
+
+`/VirtualHostBase/https/example.com/Plone/VirtualHostRoot/`
+
+### Rewriting sub-paths
+
+Consider the following.
+
+- `https://example.com` should have the object at `/Plone` (A Plone Site) as root.
+- `https://example.org` should have the object at `/Plone/org` (A content with id `org` inside the Plone Site) as root.
+- `https://example.com/ClassicUI` should point to the root object on Zope .
+
+The rewrite rule for `example.com` will be the following.
+
+`/VirtualHostBase/https/example.com/Plone/VirtualHostRoot/`
+
+The rewrite rule for `example.org` will be the following.
+
+`/VirtualHostBase/https/example.org/Plone/org/VirtualHostRoot/`
+
+The rewrite rule for `example.com/ClassicUI` will be the following.
+
+`/VirtualHostBase/https/example.com/VirtualHostRoot/_vh_ClassicUI/`
diff --git a/docs/plone-deployment/virtual_host.md b/docs/plone-deployment/virtual_host.md
deleted file mode 100644
index e22b9cb82..000000000
--- a/docs/plone-deployment/virtual_host.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-myst:
- html_meta:
- "description": "Virtual Hosting Services"
- "property=og:description": "Understand how to use Zope infrastructure to rewrite URLs in run time."
- "property=og:title": ""Virtual Hosting Services"
- "keywords": "Plone, Deployment, Stack, Configuration, Guide"
----
-
-# Virtual Hosting Services
-
-Zope comes with one object that helps you do virtual hosting: *Virtual Host Monster*. Virtual hosting is a way to serve many websites with one backend server.
-
-## Virtual Host Monster
-
-Zope objects need to generate their own URLs from time to time. For instance, when a Zope object has its "absolute_url" method called, it needs to return a URL which is appropriate for itself. This URL typically contains a hostname, a port, and a path. In a "default" Zope installation, this hostname, port, and path is typically what you want. But when it comes time to serve multiple websites out of a single Zope instance, each with their own "top-level" domain name, or when it comes time to integrate a Zope Folder within an existing website using Apache or another webserver, the URLs that Zope objects generate need to change to suit your configuration.
-
-A Virtual Host Monster's only job is to change the URLs which your Zope objects generate. This allows you to customize the URLs that are displayed within your Zope application, allowing an object to have a different URL when accessed in a different way. This is most typically useful, for example, when you wish to "publish" the contents of a single Zope Folder (e.g. '/FooFolder') as a URL that does not actually contain this Folder's name (e.g. as the hostname 'www.foofolder.com').
-
-The Virtual Host Monster performs this job by intercepting and deciphering information passed to Zope within special path elements encoded in the URLs of requests which come into Zope. If these special path elements are absent in the URLs of requests to the backend server, the Virtual Host Monster does nothing. If they are present, however, the Virtual Host Monster deciphers the information passed in via these path elements and causes your Zope objects to generate a URL that is different from their "default" URL.
-
-The Zope values which are affected by the presence of a Virtual Host Monster include REQUEST variables starting with URL or BASE (such as URL1, BASE2, URLPATH0), and the absolute_url() methods of objects.
-
-Virtual Host Monster configuration can be complicated because it requires that you *rewrite* URLs "on the way in" to Zope. In order for the special path elements to be introduced into the URL of the request sent to Zope, a front-end URL "rewriting" tool needs to be employed. Virtual Host Monster comes with a simple rewriting tool in the form of its *Mappings* view, or alternately you can use Apache or another webserver to rewrite URLs of requests destined to Zope for you.
-
-
-### Configuring the VirtualHostMonster
-
-The default mode for configuring the VirtualHostMonster is not to do any configuration at all! Rather, the external router or webserver modifies the request URL to signal what the *real* public URL for the request should be.
-
-If you *do* choose to change the settings of your VHM, the easiest method to do so is to use the VHM's ZMI interface.
-
-### Special VHM Path Elements 'VirtualHostBase' and 'VirtualHostRoot'
-
-A Virtual Host Monster doesn't do anything unless it sees one of the following special path elements in a URL:
-
-#### 'VirtualHostBase'
-
-If a VirtualHostMonster "sees" this name in the incoming URL, it causes {term}`Zope` objects to generate URLs with a potentially different protocol, a potentially different hostname, and a potentially different port number.
-
-#### 'VirtualHostRoot'
-
-If a VirtualHostMonster "sees" this name in the incoming URL, it causes Zope objects to generate URLs that have a potentially different "path root."
-
-### 'VirtualHostBase'
-
-The 'VirtualHostBase' declaration is typically found at the beginning of an incoming URL. A Virtual Host Monster will intercept two path elements following this name and will use them to compose a new protocol, hostname, and port number.
-
-The two path elements which must follow a 'VirtualHostBase' declaration are 'protocol' and 'hostname:portnumber'. They must be separated by a single slash. The colon and portnumber parts of the second element are optional, and if they don't exist, the Virtual Host Monster will not change the port number of Zope-generated URLs.
-
-Examples:
-
-- If a VHM is installed and a request comes into your server with the URL:
-
- ```http://backend:8080/VirtualHostBase/http/example.com```
-
- URLs generated by Zope objects will start with 'http://example.com:8080'.
-
-- If a VHM is installed in the root folder, and a request comes into your server with the URL:
-
- ```http://backend:8080/VirtualHostBase/http/example.com:80```
-
- URLs generated by Zope objects will start with 'http://example.com' (port 80 is the default port number so it is left out).
-
-- If a VHM is installed in the root folder, and a request comes into your Zope with the URL:
-
- ```http://backend:8080/VirtualHostBase/https/example.com:443```
-
- URLs generated by Zope objects will start with 'https://example.com/' (port 443 is the default https port number, so it is left off).
-
-One thing to note when reading the examples above is that if your Zope is running on a port number like 8080, and you want generated URLs to not include this port number and instead be served on the standard HTTP port (80), you must specifically include the default port 80 within the VirtualHostBase declaration, e.g. ```/VirtualHostBase/http/example.com:80```. If you don't specify the ':80', your Zope's HTTP port number will be used (which is likely not what you want).
-
-### 'VirtualHostRoot'
-
-The 'VirtualHostRoot' declaration is typically found near the end of an incoming URL. A Virtual Host Monster will gather up all path elements that *precede* and *follow* the 'VirtualHostRoot' name, traverse the Zope object hierarchy with these elements, and publish the object it finds with the path rewritten to the path element(s) that *follow* the 'VirtualHostRoot' name.
-
-This is easier to understand by example. For a URL '/a/b/c/VirtualHostRoot/d', the Virtual Host Monster will traverse "a/b/c/d" and then generate a URL with path /d.
-
-Examples:
-
-- If a VHM is installed in the root folder, and a request comes into your Zope with the URL:
-
- ```http://backend:8080/Folder/VirtualHostRoot/```
-
- The object 'Folder' will be traversed to and published, and URLs generated by Zope will start with 'http://backend:8080/', and when they are visited, they will be considered relative to 'Folder'.
-
-- If a VHM is installed in the root folder, and a request comes into your Zope with the URL:
-
- ```http://backend:8080/HomeFolder/VirtualHostRoot/Chris```
-
- The object '/Folder/Chris' will be traversed to and published, URLs generated by Zope will start with 'http://backend:8080/Chris', and when they are visited, they will be considered relative to '/HomeFolder/Chris'.
-
-### Using 'VirtualHostRoot' and 'VirtualHostBase' Together
-
-The most common sort of virtual hosting setup is one in which you create a Folder in your Zope root for each domain that you want to serve. For instance, the site https://example.com is served from a Plone Site in the Zope root named /Plone while the site https://example.org is served from another Plone Site in the Zope root named /OrgSite. In order to do this, you need to generate URLs that have both 'VirtualHostBase' and 'VirtualHostRoot' in them.
-
-To access /OrgSite as https://example.org, you would cause Zope to be visited via the following URL:
-
-```/VirtualHostBase/https://example.org/OrgSite/VirtualHostRoot/```
-
-In the same Zope instance, to access /Plone as https://example.com/, you would cause Zope to be visited via the following URL:
-
-```/VirtualHostBase/https/example.com/Plone/VirtualHostRoot/```
-
-### Rewriting sub-paths
-
-Considering the
-
-* https/example.com should have the object at /Plone (A Plone Site) as root.
-* https/example.org should have the object at /Plone/org (A content with id *org* inside the Plone Site) as root.
-* https/example.com/ClassicUI should point to the root object on Zope .
-
-The rewrite rule for `example.com` will be:
-
-```/VirtualHostBase/https/example.com/Plone/VirtualHostRoot/```
-
-The rewrite rule for `example.org` will be:
-
-```/VirtualHostBase/https/example.org/Plone/org/VirtualHostRoot/```
-
-The rewrite rule for `example.com/ClassicUI` will be:
-```/VirtualHostBase/https/example.com/VirtualHostRoot/_vh_ClassicUI/```
From 045d1f0749434fa6a5592b306b2351462742e679 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:00:28 -0800
Subject: [PATCH 04/11] Fix broken links Fix malformed `html_meta` header in
`virtual-host.md`
---
docs/effective-volto/architecture/bootstrap-volto.md | 2 +-
docs/effective-volto/development/i18n.md | 8 ++++----
docs/mastering-plone/volto_testing.md | 2 +-
docs/plone-deployment/setup.md | 4 +---
docs/plone-deployment/virtual-host.md | 2 +-
docs/volto-customization/installation.md | 2 +-
6 files changed, 9 insertions(+), 11 deletions(-)
diff --git a/docs/effective-volto/architecture/bootstrap-volto.md b/docs/effective-volto/architecture/bootstrap-volto.md
index 96c3b5b6a..5bd5e1f27 100644
--- a/docs/effective-volto/architecture/bootstrap-volto.md
+++ b/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:
diff --git a/docs/effective-volto/development/i18n.md b/docs/effective-volto/development/i18n.md
index 6d8d60bd6..2424e0a38 100644
--- a/docs/effective-volto/development/i18n.md
+++ b/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({
diff --git a/docs/mastering-plone/volto_testing.md b/docs/mastering-plone/volto_testing.md
index 3b448e557..7a235eac2 100644
--- a/docs/mastering-plone/volto_testing.md
+++ b/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)=
diff --git a/docs/plone-deployment/setup.md b/docs/plone-deployment/setup.md
index f8d211214..774b149d2 100644
--- a/docs/plone-deployment/setup.md
+++ b/docs/plone-deployment/setup.md
@@ -127,9 +127,7 @@ You can also configure settings for Docker Desktop.
Under {guilabel}`Prefences > Resources > Advanced`, you can configure appropriate settings for virtual disk limit and memory.
```{seealso}
-- [Change Docker Desktop settings on Mac](https://docs.docker.com/desktop/settings/#advanced)
-- [Change Docker Desktop settings on Windows](https://docs.docker.com/desktop/settings/#advanced)
-- [Change Docker Desktop settings on Linux](https://docs.docker.com/desktop/settings/#advanced)
+- [Change Docker Desktop settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/)
```
### Insufficient Docker virtual memory
diff --git a/docs/plone-deployment/virtual-host.md b/docs/plone-deployment/virtual-host.md
index d19896bfb..14449e6a8 100644
--- a/docs/plone-deployment/virtual-host.md
+++ b/docs/plone-deployment/virtual-host.md
@@ -3,7 +3,7 @@ myst:
html_meta:
"description": "Virtual Hosting Services"
"property=og:description": "Understand how to use Zope infrastructure to rewrite URLs in run time."
- "property=og:title": ""Virtual Hosting Services"
+ "property=og:title": "Virtual Hosting Services"
"keywords": "Plone, Deployment, Stack, Configuration, Guide, Virtual Host Monster, VHM"
---
diff --git a/docs/volto-customization/installation.md b/docs/volto-customization/installation.md
index 92959f329..67dc42f44 100644
--- a/docs/volto-customization/installation.md
+++ b/docs/volto-customization/installation.md
@@ -19,7 +19,7 @@ Getting started with Volto involves setting up a development environment, unders
Before you start working with this training, ensure you have the following prerequisites:
-- [Node.js LTS (>=20.x)](https://nodejs.org/en) [see instructions for installation](https://6.docs.plone.org/install/install-from-packages.html#nvm)
+- [Node.js LTS (>=20.x)](https://nodejs.org/en) [see instructions for installation](https://6.docs.plone.org/install/create-project.html#nvm)
- [Python](https://www.python.org/) - See below for specific versions.
- [pipx](https://pipx.pypa.io/stable/)
- [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating)
From 3bd4a32b42ae708e875d69b85bad21f5cf9fe77c Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:03:22 -0800
Subject: [PATCH 05/11] Web server is two words
---
docs/effective-volto/architecture/CORS.md | 2 +-
docs/mastering-plone-5/buildout_1.md | 2 +-
docs/mastering-plone-5/deployment_sites.md | 2 +-
docs/mastering-plone-5/restapi.md | 2 +-
docs/plone-deployment/plone-stack.md | 18 +++++++++---------
docs/plone-deployment/project-start.md | 2 +-
docs/plone-deployment/virtual-host.md | 4 ++--
7 files changed, 16 insertions(+), 16 deletions(-)
diff --git a/docs/effective-volto/architecture/CORS.md b/docs/effective-volto/architecture/CORS.md
index 303410eb3..d9b904f20 100644
--- a/docs/effective-volto/architecture/CORS.md
+++ b/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.
diff --git a/docs/mastering-plone-5/buildout_1.md b/docs/mastering-plone-5/buildout_1.md
index 4c34a9944..c3b1fcd3c 100644
--- a/docs/mastering-plone-5/buildout_1.md
+++ b/docs/mastering-plone-5/buildout_1.md
@@ -104,7 +104,7 @@ Even in smaller buildouts this is a useful feature. We are using [collective.rec
The omelette recipe needs to know which eggs to reference. We want the same eggs that our instance uses, so we reference the eggs of the instance instead of repeating the whole list.
-Another example: Say you create configuration files for a webserver like nginx, you can define the target port for the reverse proxy by looking it up from the zope2instance recipe.
+Another example: Say you create configuration files for a web server like nginx, you can define the target port for the reverse proxy by looking it up from the zope2instance recipe.
Configuring complex systems always involves a lot of duplication of information. Using references in the buildout configuration allows you to minimize these duplications.
```
diff --git a/docs/mastering-plone-5/deployment_sites.md b/docs/mastering-plone-5/deployment_sites.md
index b0ef430fa..381d0f685 100644
--- a/docs/mastering-plone-5/deployment_sites.md
+++ b/docs/mastering-plone-5/deployment_sites.md
@@ -64,7 +64,7 @@ Load balancer (nginx or haproxy)
|
-Webserver (nginx)
+Web server (nginx)
```
Deploying Plone and production-setups are outside the scope for this training.
diff --git a/docs/mastering-plone-5/restapi.md b/docs/mastering-plone-5/restapi.md
index d5905676a..2a12e23ce 100644
--- a/docs/mastering-plone-5/restapi.md
+++ b/docs/mastering-plone-5/restapi.md
@@ -143,7 +143,7 @@ A big advantage of Vue.js over other frameworks for our purpose is that it doesn
NodeJS..
Our focus is Plone and interacting with {py:mod}`plone.restapi`, and `Vue.js` perfectly suits our needs
-because it simply lets us use Plone as our development webserver.
+because it simply lets us use Plone as our development web server.
To get started, we create a new subdirectory of {file}`browser` named {file}`talklist`.
diff --git a/docs/plone-deployment/plone-stack.md b/docs/plone-deployment/plone-stack.md
index 9cd9a153d..1aeadd410 100644
--- a/docs/plone-deployment/plone-stack.md
+++ b/docs/plone-deployment/plone-stack.md
@@ -14,19 +14,19 @@ This guide won't cover the integration of a web accelerator or the setup of an e
## 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 {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 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
@@ -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,7 +63,7 @@ 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
@@ -76,9 +76,9 @@ In a multi-server environment, load distribution and redundancy are achieved thr
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)
diff --git a/docs/plone-deployment/project-start.md b/docs/plone-deployment/project-start.md
index 4381fb76c..7f2e768a0 100644
--- a/docs/plone-deployment/project-start.md
+++ b/docs/plone-deployment/project-start.md
@@ -70,7 +70,7 @@ In both terminals, press {kbd}`Ctrl-C`.
## Running Docker Compose
-Docker Compose is suitable for reviewing your development progress or exploring the project. It comprises four services: {term}`Traefik` webserver, Frontend, Backend, and a `Postgres` database, mimicking a production environment.
+Docker Compose is suitable for reviewing your development progress or exploring the project. It comprises four services: {term}`Traefik` web server, Frontend, Backend, and a `Postgres` database, mimicking a production environment.
```{note}
A secondary Backend route, `/ClassicUI`, mirrors `http://localhost:8080/Plone`. It's secured with Basic Authentication, default credentials being **admin/admin**.
diff --git a/docs/plone-deployment/virtual-host.md b/docs/plone-deployment/virtual-host.md
index 14449e6a8..caa1ed43a 100644
--- a/docs/plone-deployment/virtual-host.md
+++ b/docs/plone-deployment/virtual-host.md
@@ -13,7 +13,7 @@ Zope comes with one object that helps you do virtual hosting: *Virtual Host Mons
## Virtual Host Monster
-Zope objects need to generate their own URLs from time to time. For instance, when a Zope object has its "absolute_url" method called, it needs to return a URL which is appropriate for itself. This URL typically contains a hostname, a port, and a path. In a "default" Zope installation, this hostname, port, and path is typically what you want. But when it comes time to serve multiple websites out of a single Zope instance, each with their own "top-level" domain name, or when it comes time to integrate a Zope Folder within an existing website using Apache or another webserver, the URLs that Zope objects generate need to change to suit your configuration.
+Zope objects need to generate their own URLs from time to time. For instance, when a Zope object has its "absolute_url" method called, it needs to return a URL which is appropriate for itself. This URL typically contains a hostname, a port, and a path. In a "default" Zope installation, this hostname, port, and path is typically what you want. But when it comes time to serve multiple websites out of a single Zope instance, each with their own "top-level" domain name, or when it comes time to integrate a Zope Folder within an existing website using Apache or another web server, the URLs that Zope objects generate need to change to suit your configuration.
A Virtual Host Monster's only job is to change the URLs which your Zope objects generate. This allows you to customize the URLs that are displayed within your Zope application, allowing an object to have a different URL when accessed in a different way. This is most typically useful, for example, when you wish to "publish" the contents of a single Zope Folder (e.g. `/FooFolder`) as a URL that does not actually contain this Folder's name (for example, as the hostname `www.foofolder.com`).
@@ -26,7 +26,7 @@ Virtual Host Monster configuration can be complicated because it requires that y
### Configuring the Virtual Host Monster
-The default mode for configuring the Virtual Host Monster is not to do any configuration at all! Rather, the external router or webserver modifies the request URL to signal what the *real* public URL for the request should be.
+The default mode for configuring the Virtual Host Monster is not to do any configuration at all! Rather, the external router or web server modifies the request URL to signal what the *real* public URL for the request should be.
If you *do* choose to change the settings of your VHM, the easiest method to do so is to use the VHM`s ZMI interface.
From 9d2833d2cd122491db66cfdf600e837828b3c080 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:05:32 -0800
Subject: [PATCH 06/11] nginx is lower case
---
docs/effective-volto/deployment/seamlessmode.md | 4 ++--
docs/glossary.md | 4 ++--
docs/mastering-plone-5/installation.md | 2 +-
docs/plone-deployment/plone-stack.md | 2 +-
4 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/effective-volto/deployment/seamlessmode.md b/docs/effective-volto/deployment/seamlessmode.md
index 310fb1c32..9577bc3c8 100644
--- a/docs/effective-volto/deployment/seamlessmode.md
+++ b/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 {
diff --git a/docs/glossary.md b/docs/glossary.md
index 49ef23000..6d60abbec 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -302,8 +302,8 @@ Traefik
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.
diff --git a/docs/mastering-plone-5/installation.md b/docs/mastering-plone-5/installation.md
index 5d46e4d85..71a8ec919 100644
--- a/docs/mastering-plone-5/installation.md
+++ b/docs/mastering-plone-5/installation.md
@@ -100,7 +100,7 @@ See all the ways you can [set up Plone](https://plone.org/download)
The way we are setting up a Plone site during this class may be adequate for a small site
— or even a large one that's not very busy — but you are likely to want to do much more if you are using Plone for anything demanding.
-- Using a production web server like Apache or Nginx for URL rewriting, SSL and combining multiple, best-of-breed solutions into a single web site.
+- Using a production web server like Apache or nginx for URL rewriting, SSL and combining multiple, best-of-breed solutions into a single web site.
- Reverse proxy caching with a tool like Varnish to improve site performance.
- Load balancing to make best use of multiple core CPUs and even multiple servers.
- Optimizing cache headers and Plone's internal caching schemes with plone.app.caching.
diff --git a/docs/plone-deployment/plone-stack.md b/docs/plone-deployment/plone-stack.md
index 1aeadd410..9514188e9 100644
--- a/docs/plone-deployment/plone-stack.md
+++ b/docs/plone-deployment/plone-stack.md
@@ -16,7 +16,7 @@ This guide won't cover the integration of a web accelerator or the setup of an e
### Web server
-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.
+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 {doc}`virtual-host`.
From 890978ed7be386b032447513c4a950087416c765 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:20:36 -0800
Subject: [PATCH 07/11] Add reference to training choices. Simplify markup with
naked links. Use inline literal markup for inline literals. Remove bold style
from already bold headings Use `{guilabel}` for UI labels
---
docs/plone-deployment/intro.md | 2 ++
docs/plone-deployment/plone-docker-images.md | 19 +++++------
docs/plone-deployment/plone-stack.md | 6 ++--
docs/plone-deployment/project-new.md | 36 ++++++++++----------
4 files changed, 32 insertions(+), 31 deletions(-)
diff --git a/docs/plone-deployment/intro.md b/docs/plone-deployment/intro.md
index cd36e75d4..f023e19d7 100644
--- a/docs/plone-deployment/intro.md
+++ b/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
diff --git a/docs/plone-deployment/plone-docker-images.md b/docs/plone-deployment/plone-docker-images.md
index 29d73ac7b..49fe83279 100644
--- a/docs/plone-deployment/plone-docker-images.md
+++ b/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.
diff --git a/docs/plone-deployment/plone-stack.md b/docs/plone-deployment/plone-stack.md
index 9514188e9..7ae42faa7 100644
--- a/docs/plone-deployment/plone-stack.md
+++ b/docs/plone-deployment/plone-stack.md
@@ -26,7 +26,7 @@ To understand the rewrite rules used in Traefik, please read our reference about
### 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 web server.
+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
@@ -43,7 +43,7 @@ The database layer can range from a simple ZODB with file storage to more scalab
#### Without Specialized Database
```
-Web server -> Plone Frontend -> Plone Backend (file storage).
+Web server → Plone Frontend → Plone Backend (file storage)
```
```{note}
@@ -71,7 +71,7 @@ Web server → Web Accelerator → Plone Frontend → Plone Backend → Database
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
```
diff --git a/docs/plone-deployment/project-new.md b/docs/plone-deployment/project-new.md
index 626cfbff5..f88c13e2a 100644
--- a/docs/plone-deployment/project-new.md
+++ b/docs/plone-deployment/project-new.md
@@ -9,7 +9,7 @@ myst:
# Create a new Project
-As highlighted in the {doc}`intro`'s Training Choices, GitHub is essential for building Docker images automatically in this training.
+As highlighted in the {doc}`intro`'s {ref}`deployment-training-choices`, GitHub is essential for building Docker images automatically in this training.
The steps can be adapted for other providers like GitLab.
## Generating the Codebase
@@ -23,12 +23,12 @@ pipx run cookieplone project
Answer the prompts as they appear. You can either accept the default values or enter your own.
```{warning}
-For participants of **Plone Conference 2024**, please use the following settings:
+For participants in **Plone Conference 2024**, please use the following settings:
-- `Project Title`: **Plone Conference Training**
-- `Project Slug`: **ploneconf2024**
-- `Project URL`: **ploneconf2024-\<your-github-username\>.tangrama.com.br**
-- `GitHub Username or Organization`: **\<your-github-username\>**
+- {guilabel}`Project Title`: **Plone Conference Training**
+- {guilabel}`Project Slug`: **ploneconf2024**
+- {guilabel}`Project URL`: **ploneconf2024-\<your-github-username\>.tangrama.com.br**
+- {guilabel}`GitHub Username or Organization`: **\<your-github-username\>**
```
An example interaction with the `Cookieplone` wizard is shown below:
@@ -116,30 +116,30 @@ make check
## Create a Repository on GitHub
-### 1. **Login to GitHub**
+### 1. Login to GitHub
Visit [GitHub](https://github.com) and log in.
-### 2. **Create a New Repository**
+### 2. Create a New Repository
Click the '+' icon in the upper right corner, select 'New repository', and fill in the details:
-- **Repository name:** ploneconf2024
-- **Description:** Plone Conference 2024 Training
-- **Visibility:** Public
+- {guilabel}`Repository name`: `ploneconf2024`
+- {guilabel}`Description`: `Plone Conference 2024 Training`
+- {guilabel}`Visibility`: `Public`
Click 'Create repository'.
## Initialize and Push to the Git Repository
-### 1. **Initialize Git**
+### 1. Initialize Git
Initializes a new Git repository and begins tracking an existing directory.
```shell
git init .
```
-### 2. **Add Files**
+### 2. Add Files
stages changes for commit, meaning it tracks the new files (in this case, all files in the directory with `.`). Staging lets you select which changes you want to commit.
@@ -147,27 +147,27 @@ stages changes for commit, meaning it tracks the new files (in this case, all fi
git add .
```
-### 3. **Initial Commit**
+### 3. Initial Commit
Saves the staged changes along with a brief log message describing the changes.
-Replace `"Initial commit"` with a descriptive message if needed. It's the first commit,
+Replace "`Initial commit`" with a descriptive message if needed. It's the first commit,
so we typically label it as the "Initial commit."
```shell
git commit -m "Initial commit"
```
-### 4. **Link Local Repository to Remote Repository**
+### 4. Link Local Repository to Remote Repository
Connect your local repository to the remote server. First replace `<your-github-username>` with your actual GitHub username.
-'origin' is the default name given to the remote repository, and we also set the default branch to be `main`.
+`origin` is the default name given to the remote repository, and we also set the default branch to be `main`.
```shell
git remote add origin git@github.com:<your-github-username>/ploneconf2024.git
git branch -M main
```
-### 4. **Push to GitHub**
+### 4. Push to GitHub
Push your commits to the remote repository hosted on GitHub. This command will trigger the GitHub Actions that test the codebase and
generate Docker images for the Backend and for the Frontend.
From f4b7787189bf45fa9afb7c5019eaee956fc9b112 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:31:13 -0800
Subject: [PATCH 08/11] Fix emphasize lines spec
---
docs/plone-deployment/project-new.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/plone-deployment/project-new.md b/docs/plone-deployment/project-new.md
index f88c13e2a..709b1dc07 100644
--- a/docs/plone-deployment/project-new.md
+++ b/docs/plone-deployment/project-new.md
@@ -34,7 +34,8 @@ For participants in **Plone Conference 2024**, please use the following settings
An example interaction with the `Cookieplone` wizard is shown below:
```{code-block} console
-:emphasize-lines: 1,3,4,10,11,19,
+:emphasize-lines: 1,3,4,10,11,20
+
[1/17] Project Title (Project Title): Plone Conference Training
[2/17] Project Description (A new project using Plone 6.):
[3/17] Project Slug (Used for repository id) (plone-conference-training): ploneconf2024
From 95114bbfe7392691d18110c91a3426002f9dbf0c Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:32:33 -0800
Subject: [PATCH 09/11] Use naked URLs and other MyST markup fixes
---
docs/plone-deployment/project-start.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/plone-deployment/project-start.md b/docs/plone-deployment/project-start.md
index 7f2e768a0..5935d5d48 100644
--- a/docs/plone-deployment/project-start.md
+++ b/docs/plone-deployment/project-start.md
@@ -9,11 +9,11 @@ myst:
# Start the Project
-The {term}`cookieplone` equips you with essential tools to initiate a local development environment. The {doc}`project-new` offers two methods to launch your project: manually starting the Backend and Frontend servers, or utilizing a Docker Compose stack.
+The {term}`cookieplone` equips you with essential tools to initiate a local development environment. {doc}`project-new` offers two methods to launch your project: manually starting the Backend and Frontend servers, or utilizing a Docker Compose stack.
## Running Local Servers
-This method requires two terminals as both Backend and Frontend operate in `foreground mode`. It's optimal for local development due to its swift change and restart cycle. However, accessing each server on their internal ports can lead to CORS issues in real-world deployments.
+This method requires two terminals as both Backend and Frontend operate in "foreground mode". It's optimal for local development due to its swift change and restart cycle. However, accessing each server on their internal ports can lead to CORS issues in real-world deployments.
### Starting the Backend
@@ -25,11 +25,11 @@ make backend-start
This command initiates the Backend server. Upon successful startup, you'll observe:
-```
+```console
... INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080
```
-Indicating the server is operational and awaiting requests on port 8080. Visit [http://localhost:8080](http://localhost:8080) to explore.
+Indicating the server is operational and awaiting requests on port 8080. Visit http://localhost:8080 to explore.
```{figure} _static/start_backend_localhost.png
:alt: Backend server initiation at http://localhost:8080
@@ -52,7 +52,7 @@ The Frontend initiation takes longer due to the initial codebase compilation. A
🎭 Volto started at 0.0.0.0:3000 🚀
```
-Signifying the Frontend server is active on port 3000. Access it via [http://localhost:3000](http://localhost:3000).
+Signifying the Frontend server is active on port 3000. Access it via http://localhost:3000.
```{figure} _static/start_frontend_localhost.png
:alt: Frontend server initiation at http://localhost:3000
@@ -108,7 +108,7 @@ Re-run `make stack-status`, and both Backend and Frontend should now display a *
### Accessing the Site
-Your website is accessible at [http://ploneconf2024.localhost](http://ploneconf2024.localhost).
+Your website is accessible at http://ploneconf2024.localhost.
```{figure} _static/start_stack_localhost.png
:alt: Accessing the site at http://ploneconf2024.localhost
From c4a22593d5e829aa9b94ba1007c91902994995d0 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:43:35 -0800
Subject: [PATCH 10/11] Clean up MyST syntax
---
docs/plone-deployment/project-edit.md | 64 +++++++++++++--------------
1 file changed, 31 insertions(+), 33 deletions(-)
diff --git a/docs/plone-deployment/project-edit.md b/docs/plone-deployment/project-edit.md
index e16da8914..70cb7ce92 100644
--- a/docs/plone-deployment/project-edit.md
+++ b/docs/plone-deployment/project-edit.md
@@ -65,54 +65,52 @@ We'll now add GitHub OAuth authentication, involving both Backend and Frontend a
Follow GitHub's guide on [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app), using the following configurations:
-- **Application Name**: `plone-conference-local`
-- **Homepage URL**: `http://ploneconf2024.localhost`
-- **Application Description**: `Plone Conference 2024`
-- **Authorization Callback URL**: `http://ploneconf2024.localhost/`
+- {guilabel}`Application Name`: `plone-conference-local`
+- {guilabel}`Homepage URL`: `http://ploneconf2024.localhost`
+- {guilabel}`Application Description`: `Plone Conference 2024`
+- {guilabel}`Authorization Callback URL`: `http://ploneconf2024.localhost/`
### Backend: Installing `pas.plugins.authomatic`
-Modify `backend/setup.py` to include `pas.plugins.authomatic` in `install_requires`. Also, update `backend/src/ploneconf2024/dependencies.zcml` to load the package configuration during Plone Backend startup.
+Modify {file}`backend/setup.py` to include `pas.plugins.authomatic` in `install_requires`. Also, update {file}`backend/src/ploneconf2024/dependencies.zcml` to load the package configuration during Plone Backend startup.
### Frontend: Installing `volto-authomatic`
-Add `@plone-collective/volto-authomatic` to the `addons` and `dependencies` sections of `frontend/packages/volto-ploneconf2024/package.json`. Run `make frontend-install` to update the dependencies.
+Add `@plone-collective/volto-authomatic` to the `addons` and `dependencies` sections of {file}`frontend/packages/volto-ploneconf2024/package.json`. Run `make frontend-install` to update the dependencies.
### Activating and Configuring the Add-on
````{note}
-To ensure the name `ploneconf24.localhost` points to the address `127.0.0.1`, we need to edit the file located at:
+To ensure the name `ploneconf24.localhost` points to the address `127.0.0.1`, we need to edit the file located at {file}`C:\Windows\System32\Drivers\etc\hosts`.
-`C:\Windows\System32\Drivers\etc\hosts`
+1. Open the {guilabel}`Start Menu` and search for "Notepad".
+ Right-click on it and choose {guilabel}`Run as administrator`.
+ If Windows asks if you want the application to make changes to the system, click {guilabel}`Yes`.
+ (If you don't open Notepad as an administrator, you won't be able to modify the `hosts` file.)
-1. Open the Start Menu and search for **Notepad**.
- Right-click on it and choose **Run as administrator**.
- If Windows asks if you want the application to make changes to the system, click **Yes**.
- (If you don't open Notepad as an administrator, you won't be able to modify the `hosts` file.)
+2. In Notepad, click {menuselection}`File --> Open`.
+ Then navigate to the folder {file}`C:\Windows\System32\Drivers\etc`.
-2. In Notepad, click **File » Open**.
- Then navigate to the following folder:
- `C:` » `Windows` » `System32` » `Drivers` » `etc`.
+3. In the file dialog, change the filter from {guilabel}`Text Documents (*.txt)` to {guilabel}`All Files (*.*)`.
+ You should now see the `hosts` file.
+ Select it and click {guilabel}`Open`.
-3. In the file dialog, change the filter from **Text Documents (*.txt)** to **All Files (*.*)**.
- You should now see the `hosts` file. Select it and click **Open**.
+4. At the end of the file, add the following line:
-4. At the end of the file, add the following line:
+ ```text
+ 127.0.0.1 ploneconf24.localhost
+ ```
-```
-127.0.0.1 ploneconf24.localhost
-```
-
-5. Save the file.
+5. Save the file.
-6. Open PowerShell and confirm that the name resolution is working correctly by typing:
+6. Open PowerShell and confirm that the name resolution is working correctly by typing:
-```shell
-ping ploneconf24.localhost
-```
+ ```shell
+ ping ploneconf24.localhost
+ ```
````
-Start the Docker Compose stack with `make stack-start`. Navigate to [http://ploneconf2024.localhost/ClassicUI/login](http://ploneconf2024.localhost/ClassicUI/login) and authenticate.
+Start the Docker Compose stack with `make stack-start`. Navigate to http://ploneconf2024.localhost/ClassicUI/login.
Install `pas.plugins.authomatic` from the {guilabel}`Add-ons` control panel and configure it with the following JSON configuration, replacing `KEYHERE` and `SECRETHERE` with your GitHub OAuth application's client ID and secret.
@@ -146,19 +144,19 @@ Install `pas.plugins.authomatic` from the {guilabel}`Add-ons` control panel and
### Authenticating with GitHub
-Visit [http://ploneconf2024.localhost/login](http://ploneconf2024.localhost/login) and log in using GitHub.
+Visit http://ploneconf2024.localhost/login and log in using GitHub.
### Configure the OAuth user permissions
-By default, `pas.plugins.authomatic` will not assign any role or group to an user authenticated with GitHub, but you can, using an existing user (i.e. `admin`), assign the OAuthed user to groups and grant permissions.
+By default, `pas.plugins.authomatic` will not assign any role or group to an user authenticated with GitHub, but you can, using an existing user such as `admin`, assign the OAuthed user to groups and grant permissions.
-Back in the tab you are using to access the `ClassicUI`, visit the control panel {guilabel}`Users > Users`.
+Back in the tab you are using to access the `ClassicUI`, visit the control panel {menuselection}`Users --> Users`.
For the {guilabel}`User name` row, check appropriate permissions.
For the purpose of this training, check {guilabel}`Manager`, then click {guilabel}`Apply changes`.
```{warning}
If you need to authenticate bypassing OAuth, there are fallback login forms:
-* Backend: Available at [http://ploneconf2024.localhost/ClassicUI/failsafe_login](http://ploneconf2024.localhost/ClassicUI/failsafe_login).
-* Frontend: Available at [http://ploneconf2024.localhost/fallback_login](http://ploneconf2024.localhost/fallback_login).
+- Backend: Available at http://ploneconf2024.localhost/ClassicUI/failsafe_login.
+- Frontend: Available at http://ploneconf2024.localhost/fallback_login.
```
From 017cc8251351f1400cb8c27410fa1d68aba70727 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 27 Nov 2024 01:52:26 -0800
Subject: [PATCH 11/11] Clean up MyST syntax
---
docs/plone-deployment/deploy.md | 36 ++++++++++++++++-----------------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/docs/plone-deployment/deploy.md b/docs/plone-deployment/deploy.md
index 8500a1e2d..b5f672149 100644
--- a/docs/plone-deployment/deploy.md
+++ b/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.