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/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/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/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/glossary.md b/docs/glossary.md index 92b1e9775..6d60abbec 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,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. diff --git a/docs/mastering-plone-5/buildout_1.md b/docs/mastering-plone-5/buildout_1.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/mastering-plone-5/deployment_sites.md b/docs/mastering-plone-5/deployment_sites.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/mastering-plone-5/installation.md b/docs/mastering-plone-5/installation.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/mastering-plone-5/restapi.md b/docs/mastering-plone-5/restapi.md new file mode 100644 index 000000000..e69de29bb 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/deploy.md b/docs/plone-deployment/deploy.md index ded00f687..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 `` 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 ``, 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. 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 7e0c3d603..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 @@ -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. 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 < 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 @@ -71,14 +71,14 @@ Webserver → 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 ``` -#### 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-edit.md b/docs/plone-deployment/project-edit.md index dc98fb7eb..70cb7ce92 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,62 +59,60 @@ 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 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. +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 { @@ -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. ``` diff --git a/docs/plone-deployment/project-new.md b/docs/plone-deployment/project-new.md index 626cfbff5..709b1dc07 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,18 +23,19 @@ 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-\.tangrama.com.br** -- `GitHub Username or Organization`: **\** +- {guilabel}`Project Title`: **Plone Conference Training** +- {guilabel}`Project Slug`: **ploneconf2024** +- {guilabel}`Project URL`: **ploneconf2024-\.tangrama.com.br** +- {guilabel}`GitHub Username or Organization`: **\** ``` 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 @@ -116,30 +117,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 +148,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 `` 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:/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. diff --git a/docs/plone-deployment/project-start.md b/docs/plone-deployment/project-start.md index 55141dceb..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 @@ -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**. @@ -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 @@ -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 @@ -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-.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 b874564f9..774b149d2 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. -Choose a code editor you’re comfortable with, such as VSCode, PyCharm, Sublime, VI, or Emacs. +### 2. Code Editor -### 3. **Python** +Choose a code editor you're comfortable with, such as VSCode, PyCharm, Sublime, VI, or Emacs. + +### 3. Python Install Python version 3.11.x or 3.12.x, ensuring that `pip` is included and updated. @@ -37,10 +40,10 @@ 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** +### 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`. +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: @@ -124,11 +127,9 @@ 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 +### Insufficient Docker virtual memory Docker requires sufficient memory to install and build images. See the previous item for details. diff --git a/docs/plone-deployment/virtual-host.md b/docs/plone-deployment/virtual-host.md new file mode 100644 index 000000000..caa1ed43a --- /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 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`). + +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 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. + +### 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/``` 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)