Docs: faster onboarding, identify running processes, improve internal…

… proxy clarification (#3010) * Move style guide and Design principles to Developer Guidelines chapter. * They slow down readers who want to evaluate Volto as it is not relevant to them at that point in the TOC. * Also these chapters need to be updated. * Mentionning Quanta that is not finished at the beginning of the docs is red flag to readers evaluating Voto for production use. * Move the how does it work video to the learning resources, the page is too small now. First attempt to better describe in getting started why we only set up a javascript development environemtn by listing the running processes. Use the same principle in the internal proxy documentation, list the processes, add the default value for the frontend API PATH, and describe the default request flow that prevents CORS issues. * Rewording, text cleanup, better tip on why not to use the internal proxy in production. * Fix SSR abbreviation Remove part of apiPATH, but disabling proxy through the config object still needs to be fixed. * Finish editing chapter, clean up merge line. * Remove paragraph on disabling the proxy as was already done on the main branch. * Add changelog entry to make CI happy.
plone · Feb 1, 2022 · 5b50727 · 5b50727
1 parent f3f0c19
commit 5b50727
Show file tree

Hide file tree

Showing 11 changed files with 89 additions and 47 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,11 @@
 
 ### Internal
 
+### Docs
+
+Update documentation for internal proxy & other smaller reorganisation for quicker onboarding of 
+new users/evaluators. @fredvd
+
 ## 14.7.0 (2022-01-28)
 
 ### Feature

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -20,12 +20,9 @@ extra_css:
 
 nav:
  - Getting Started:
- - Bootstrap Volto: 'getting-started/install.md'
+ - Installing Volto: 'getting-started/install.md'
  - Developer roadmap: 'getting-started/roadmap.md'
  - Learning resources: 'getting-started/others.md'
- - How does it work under the hood: 'getting-started/howdoesitwork.md'
- - Design principles: 'design-principles/index.md'
- - Style Guide: 'style-guide/index.md'
  - Configuration:
  - What is configurable?: 'configuration/how-to.md'
  - Settings reference guide: 'configuration/settings-reference.md'
@@ -80,6 +77,8 @@ nav:
  - Performance improvements: 'deploying/performance.md'
  - Upgrade Guide: 'upgrade-guide/index.md'
  - Developer Guidelines:
+ - Design principles: 'developer-guidelines/design-principles.md'
+ - Style Guide: 'developer-guidelines/style-guide.md'
  - Language features: 'developer-guidelines/language-features.md'
  - Linting: 'developer-guidelines/linting.md'
  - React: 'developer-guidelines/react.md'

diff --git a/docs/source/configuration/backend.md b/docs/source/configuration/backend.md
@@ -1,23 +1,20 @@
 # Backend configuration
 
 ## plone.volto
+<<<<<<< HEAD
+In order to fully support all Volto features, the Plone backend content API needs to be prepared for Volto. The add'on `plone.volto` does all the heavy lifting for you and is ready to use in your own projects. We used it in our Getting Started section.
 
-In order to fully support all Volto features, the Plone backend, needs to be prepared for
-Volto. This involves configuration, add-ons installation and some patches to the core.
-The add'on `plone.volto` does all the heavy lifting for you and it's ready to use
-in your own projects. We used it in our Getting Started section.
-
-However, this package is oppinionated and might not fit your needs, so if you want to
-use your own integration package instead, just take a look at the features it provides,
+This package is slightly opinionated but provides the correct default settings for when
+you want to start with Volto. If you have advanced needs or want to move the setting to
+your own integration package instead, just take a look at the features it provides,
 copy the ones you need for your project and create your own integration package.
 
 https://github.com/plone/plone.volto
 
 !!! tip
  From Volto 5.1 and above, Volto features an internal proxy to your API server. So
- you don't have to deal with CORS. It's enabled by default, pointing to the server
- specified in the `devProxyToApiPath` Volto settings (http://localhost:8080/Plone).
- See [here](../configuration/internalproxy.md) for more details.
+ you don't have to deal with CORS issues. It's enabled by default, pointing to the server specified in the `devProxyToApiPath` Volto settings
+ (http://localhost:8080/Plone). See [here](../configuration/internalproxy.md) for more information.
 
 ## Install a Plone backend locally without Docker
 

diff --git a/docs/source/configuration/how-to.md b/docs/source/configuration/how-to.md
@@ -14,9 +14,10 @@ like:
 const absoluteUrl = `${config.settings.apiPath}/${content.url}`
 ```
 
-Both add-ons and projects can extend Volto's configuration registry. First the add-ons
-configuration is applied, in the order they are defined in `package.json`, then finally
-the project configuration is applied. Visualized like a pipe would be:
+Both the main project and individual add-ons can extend Volto's configuration registry.
+First the add-ons configuration is applied, in the order they are defined in 
+`package.json`, then finally the project configuration is applied. Visualized like
+a pipe would be:
 
 > Default Volto configuration -> Add-on 1 -> Add-on 2 -> ... -> Add-on n -> Project
 

diff --git a/docs/source/configuration/internalproxy.md b/docs/source/configuration/internalproxy.md
@@ -1,24 +1,41 @@
-# Internal proxy to API
+# Internal proxy to content backend API
+
+The server side Volto SSR process (based on Razzle) has an internal proxy to the backend API
+enabled by default.
 
-While in development, Volto has an internal proxy to the backend API enabled by default.
 It provides a better developer experience out of the box, so the developer doesn't has to
 deal with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) and can focus on
 develop/test drive/demo Volto.
 
+To understand the need for the internal proxy, there are three processes running in a Volto website:
+
+1. A frontend web application running in your browser (Javascript)
+2. A Node.js server process that delivers the javascript to the client and does
+ Server Side Rendering (SSR) of your pages on first request (Javascript, the
+ Razzle package is used for SSR)
+3. A Plone server process that stores and delivers all content through a REST API (Python)
+
 ## Configuration
 
-By default, Volto expects a Plone backend located at `http://localhost:8080/Plone`.
-These are the settings that allows you to configure the API and how the proxy works:
+The default values from Volto configuration expect a Plone content backend located at `http://localhost:8080/Plone`.
 
-- `apiPath` [API_PATH] - URL of the backend, used through Volto. By default, the proxy URL.
-- `devProxyToApiPath` - The real backend URL, used by the proxy. By default, `http://localhost:8080/Plone`
+What happens in the default development configuration/setup:
 
-!!! tip
- You don't want to deal with CORS in your production deployments, so using the proxy is only meant to be enabled in development mode (e.g `yarn start`). However, for convenience and for testing/demoing using the stock build, it's also enabled in production mode since Volto 14.
+* The client side Volto javascript files precooked HTML (SSR) is served from http://localhost:3000/ by the NodeJS server process
+* The client javascript does API requests for content and other data on the same url at http://localhost:3000/++api++/
+* The NodeJS service its internal proxy requests the data from the Plone content backend api and delivers
+back json to the frontend.
+* The web browser application is happy, because all connections go through the same URL and no CORS related security issues will be triggered.
 
-Here are some examples.
+!!! tip
+ You could also use the internal proxy for production setups. For convenience and for
+ testing/demoing using the stock build, it is also enabled in production mode since 
+ Volto 14. But it is bad for performance because the server side running Node process
+ is also responsable for generating the SSR HTML. With Nginx, Apache or another
+ 'reverse proxy' you can also create an internal API mount which is more suited for
+ that. For more deployment information see ['Seemless mode'](/deploying/seamless-mode)
 
-### Redefining the proxy target
+### Examples redefining the proxy target
 
 You can redefine the local proxy target by using the `RAZZLE_DEV_PROXY_API_PATH` or setting `devProxyToApiPath` in the configuration object (`src/config.js`).
 
@@ -36,6 +53,8 @@ or use the environment variable:
 RAZZLE_DEV_PROXY_API_PATH=http://localhost:8081/mysite yarn start
 ```
 
+This redefines the request path from the internal proxy of the server side Node proces to the Plone content backend API, but leaves the frontend Volto process making all content requests to http://locahost:3000/++api++/
+
 ### Advanced usage
 
 See [](../recipes/environment-variables.md) for recipes on internal proxy usage.
diff --git a/docs/source/style-guide/Quanta.pdf → docs/source/developer-guidelines/Quanta.pdf b/docs/source/style-guide/Quanta.pdf → docs/source/developer-guidelines/Quanta.pdf
diff --git a/docs/source/design-principles/index.md → ...developer-guidelines/design-principles.md b/docs/source/design-principles/index.md → ...developer-guidelines/design-principles.md
diff --git a/docs/source/style-guide/index.md → ...ource/developer-guidelines/style-guide.md b/docs/source/style-guide/index.md → ...ource/developer-guidelines/style-guide.md
diff --git a/docs/source/getting-started/howdoesitwork.md b/docs/source/getting-started/howdoesitwork.md
diff --git a/docs/source/getting-started/install.md b/docs/source/getting-started/install.md
@@ -13,18 +13,37 @@ are met:
 Depending on the OS that you are using some of the following might change, they
 are assuming a MacOS/Linux machine:
 
+## Components / Processes running
+
+There are three processes continuously running when you have a working Volto website:
+
+1. A frontend web application running in your browser (Javascript)
+2. A Node.js server process that delivers the javascript to the client and does
+ Server Side Rendering (SSR) of your pages on first request (Javascript, the
+ Razzle package is used for SSR)
+3. A Plone server process that stores and delivers all content through a REST API (Python)
+
+When you start with Volto most of the first customisations you will want to make (or mabye
+ever need to make) are in the javascript code used in the browser and Razzle process. Therefore
+this getting started chapter will focus on installing a nodejs/javascript environment locally
+and suggest you start the API backend using a container. 
+
+
 ## Install nvm (NodeJS version manager)
 
-If you have a working nodejs development setup on your machine, this step is
-not required. But it's a good idea to integrate nvm for development, as it
-provides easy access to any Nodejs released version.
+If you have a working Node javascript development already set up on your machine or you prefer
+another management tool to install/maintain node this step is not needed. If you have less 
+experience with setting up javascript, it's a good idea to integrate nvm for development, as
+it provides easy access to any NodeJS released version. 
 
 1. Open a terminal console and type:
 ```bash
 touch ~/.bash_profile
-curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
+curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.39.1/install.sh | bash
 ```
 
+(Please check the latest available version of nvm on the [main README](https://github.com/nvm-sh/nvm)
+
 2. Close the terminal and open a new one or execute:
 ```
 source ~/.bash_profile
@@ -50,10 +69,8 @@ node -v
  If you're using the fish shell, you can use [nvm.fish](https://github.com/jorgebucaran/nvm.fish)
 
 !!! note
- Volto supports all currently active NodeJS LTS versions based on [NodeJS
- Releases page](https://nodejs.org/en/about/releases/). On 2021-04-30 Volto
- will not support Node 10 as it will reach its end of life.
-
+ Volto supports currently active NodeJS LTS versions based on [NodeJS
+ Releases page](https://nodejs.org/en/about/releases/), starting with Node 12 LTS. 
 ## Yarn (NodeJS package manager)
 
 Install the Yarn Classic version (not the 2.x one!), of the popular node package manager.
@@ -102,7 +119,8 @@ should not throw an error and show the current running containers.
 
 ## Run a Volto ready Plone Docker container
 
-When you have installed Docker, you can run an standard Plone Docker container with the proper configuration for Volto using the `plone.volto` add-on right away by issuing:
+When you have installed Docker, you can use the official Plone Docker container with the proper configuration for Volto using the `plone.volto` add'on right away by issuing:
+
 
 ```shell
 docker run -it --rm --name=plone \

diff --git a/docs/source/getting-started/others.md b/docs/source/getting-started/others.md
@@ -16,18 +16,26 @@ Javascript-centered trainings.
 - [React](https://training.plone.org/5/react/index.html)
 - [JavaScript For Plone Developers](https://training.plone.org/5/javascript/index.html)
 
-## PloneConf 2021
+## How does it work under the hood
 
-[Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi)
+You can watch the talk during the World Plone Day 2021:
 
-## PloneConf 2020
+<iframe width="560" height="315" src="https://www.youtube.com/embed/kHec4MXH8vo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
-[Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3)
+## Presentations at the last two PloneConf's
 
-## PloneConf 2019
+In recent years the new Volto frontend for Plone has been presented in more and more talks from
+our yearly Conferences:
+
+- [PloneConf 2021 Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi)
+
+- [PloneConf 2020 Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3)
 
-PloneConf 2019 had several Volto-relevant presentations.
 
+## PloneConf 2019
+
+PloneConf 2019 and other events have several Volto-relevant presentations, but not stored in a
+single playlist:
 ### Howtos
 
 - [Rob Gietema - How to create your own Volto site!](https://www.youtube.com/watch?v=3QLN8tsjjf4)