diff --git a/CHANGELOG.md b/CHANGELOG.md index 7791f834f1..c3740b23d3 100644 --- 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 index 1edc8ca117..864f35cd9b 100644 --- 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 index f6555e8f29..d51fed8d6d 100644 --- 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 index a3c4ec90a2..b5793c2bb9 100644 --- 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 index 182eabf7c6..dda1e48bed 100644 --- 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 b/docs/source/developer-guidelines/Quanta.pdf similarity index 100% rename from docs/source/style-guide/Quanta.pdf rename to docs/source/developer-guidelines/Quanta.pdf diff --git a/docs/source/design-principles/index.md b/docs/source/developer-guidelines/design-principles.md similarity index 100% rename from docs/source/design-principles/index.md rename to docs/source/developer-guidelines/design-principles.md diff --git a/docs/source/style-guide/index.md b/docs/source/developer-guidelines/style-guide.md similarity index 100% rename from docs/source/style-guide/index.md rename to docs/source/developer-guidelines/style-guide.md diff --git a/docs/source/getting-started/howdoesitwork.md b/docs/source/getting-started/howdoesitwork.md deleted file mode 100644 index 6d39f0e36d..0000000000 --- a/docs/source/getting-started/howdoesitwork.md +++ /dev/null @@ -1,5 +0,0 @@ -# How does it work under the hood - -You can watch the talk during the World Plone Day 2021: - - diff --git a/docs/source/getting-started/install.md b/docs/source/getting-started/install.md index 0074b33018..3851ea3cdc 100644 --- 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 index f3739fc8d2..7d462408a2 100644 --- 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 + -[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)