diff --git a/docs/_inc/_hardware-requirements.md b/docs/_inc/_hardware-requirements.md new file mode 100644 index 000000000..76bd3c02f --- /dev/null +++ b/docs/_inc/_hardware-requirements.md @@ -0,0 +1,19 @@ +The hardware requirements below give a rough estimate of the minimum hardware setup needed for a Plone server. + +A single Plone installation is able to run many Plone sites. + +- Installation of the Plone backend and Classic UI frontend requires a minimum of 256 MB of RAM and 2GB of disk swap space. +- Installation of the Volto frontend requires a minimum of 2GB of RAM. +- After installation, running Plone requires a minimum of 256 MB RAM and 512 MB of disk swap space per Plone site. + 2 GB or more RAM per Plone site is recommended. +- Minimum 512 MB hard disk space is required. + 40 GB or more hard disk space is recommended. + + +````{warning} +{term}`Add-on` products and caching solutions may also increase RAM and disk swap space requirements. +To avoid RAM and disk swap limitations, we recommend either temporarily resizing your remote machine to accommodate the build, or build your images locally and upload them to an image store, such as [Docker Hub](https://hub.docker.com/) or [GitHub Packages](https://github.com/features/packages). +```{seealso} +[How much RAM is required to build a Volto front end?](https://community.plone.org/t/how-much-ram-is-required-to-build-a-volto-front-end/17949) and [Dealing with heap exhaustion while building Volto 17 on limited-RAM host](https://community.plone.org/t/dealing-with-heap-exhaustion-while-building-volto-17-on-limited-ram-host/18078). +``` +```` diff --git a/docs/_inc/_install-pillow.md b/docs/_inc/_install-pillow.md new file mode 100644 index 000000000..08aa5a3f1 --- /dev/null +++ b/docs/_inc/_install-pillow.md @@ -0,0 +1,24 @@ +``````{note} +After generating a project, then running `make install`, if you see an error message `ERROR: Failed building wheel for Pillow`, then you need to install Pillow's dependencies. + +`````{tab-set} + +````{tab-item} macOS +```shell +brew install zlib libjpeg +``` +```` + +````{tab-item} Linux +```shell +apt-get zlib libjpeg +``` +```` +````` + +You will then need to run `make install` again. + +```{seealso} +See also the Pillow documentation [External Libraries](https://pillow.readthedocs.io/en/latest/installation/building-from-source.html#external-libraries) for additional libraries that you might need. +``` +`````` diff --git a/docs/_inc/_install-python.md b/docs/_inc/_install-python.md new file mode 100644 index 000000000..4f0add878 --- /dev/null +++ b/docs/_inc/_install-python.md @@ -0,0 +1,6 @@ +Installing Python is beyond the scope of this documentation. +However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. +% TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes. +% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. + +Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. diff --git a/docs/_static/plone-classic-ui-landing-page.png b/docs/_static/plone-classic-ui-landing-page.png index 018b0af21..a4f101987 100644 Binary files a/docs/_static/plone-classic-ui-landing-page.png and b/docs/_static/plone-classic-ui-landing-page.png differ diff --git a/docs/_static/plone-classic-ui-site-page.png b/docs/_static/plone-classic-ui-site-page.png new file mode 100644 index 000000000..7c27b5ad9 Binary files /dev/null and b/docs/_static/plone-classic-ui-site-page.png differ diff --git a/docs/_static/plone-home-page.png b/docs/_static/plone-home-page.png index c670a9360..b2321e0ea 100644 Binary files a/docs/_static/plone-home-page.png and b/docs/_static/plone-home-page.png differ diff --git a/docs/_static/plone-login-page.png b/docs/_static/plone-login-page.png index 25a1d0a31..8a2f90e72 100644 Binary files a/docs/_static/plone-login-page.png and b/docs/_static/plone-login-page.png differ diff --git a/docs/glossary.md b/docs/glossary.md index 0c487f5eb..05eae946a 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -28,6 +28,25 @@ 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`. + +cookieplone-templates + [`cookieplone-templates`](https://github.com/plone/cookieplone-templates) is a collection of templates used by {term}`Cookieplone`. + +@plone/generator-volto +plone/generator-volto + ```{deprecated} Volto 18.0.0-alpha.43 + ``` + + [@plone/generator-volto](https://www.npmjs.com/package/@plone/generator-volto) is deprecated in favor of {term}`Cookieplone` since Volto 18.0.0-alpha.43. + See {ref}`upgrade-18-cookieplone-label`. + cookiecutter-plone-starter [cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter/) is a framework for jumpstarting Plone 6 projects quickly. diff --git a/docs/install/create-project-classic-ui.md b/docs/install/create-project-classic-ui.md new file mode 100644 index 000000000..c04189f92 --- /dev/null +++ b/docs/install/create-project-classic-ui.md @@ -0,0 +1,229 @@ +--- +myst: + html_meta: + "description": "Create a Plone project with Classic UI (stable release)" + "property=og:description": "Create a Plone project with Classic UI (stable release)" + "property=og:title": "Create a Plone project with Classic UI (stable release)" + "keywords": "Plone, Plone 6, Classic UI, create, project, install, cookiecutter, Cookieplone" +--- + + +(create-a-project-classic-ui-label)= + +# Create a project with Classic UI (stable release) + +This chapter describes how you can create a web application using the current **stable release** version of Plone with **Classic UI** for the frontend, while having full control over its development and deployment. + +```{seealso} +For other installation options, see {doc}`/install/index`. +``` + + +## System requirements + +Plone 6 has both hardware requirements and software pre-requisites. + + +### Hardware requirements + +```{include} /_inc/_hardware-requirements.md +``` + +### Pre-requisites for installation + +```{include} ../volto/contributing/install-operating-system.md +``` + +- Python {SUPPORTED_PYTHON_VERSIONS} +- {term}`pipx` +- {term}`GNU make` +- {term}`Git` + + +#### Python + +```{include} /_inc/_install-python.md +``` + + +#### pipx + +Install {term}`pipx`. + +```shell +pip install pipx +``` + + +#### Make + +```{include} ../volto/contributing/install-make.md +``` + + +#### Git + +```{include} ../volto/contributing/install-git.md +``` + + +## Generate the project + +After satisfying the pre-requisites, generate the project. + +```shell +pipx run cookieplone backend_addon +``` + +You will be presented with a series of prompts. +You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. +For ease of documentation, we will use the default values. + +```{tip} +See the cookiecutter's README for how to [Use options to avoid prompts](https://github.com/collective/cookiecutter-plone-starter/?tab=readme-ov-file#use-options-to-avoid-prompts). +``` + +```{important} +For {guilabel}`Project Slug`, you must not use any of the Plone core package names listed in [`constraints.txt`](https://dist.plone.org/release/6.0-latest/constraints.txt). +Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the same package. +``` + +```console +% pipx run cookieplone backend_addon +╭─────────────────────────────────── cookieplone ────────────────────────────────────╮ +│ │ +│ .xxxxxxxxxxxxxx. │ +│ ;xxxxxxxxxxxxxxxxxxxxxx; │ +│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx; │ +│ xxxxxxxxxx xxxxxxxxxx │ +│ xxxxxxxx. .xxxxxxxx │ +│ xxxxxxx xxxxxxx: xxxxxxx │ +│ :xxxxxx xxxxxxxxxx xxxxxx: │ +│ :xxxxx+ xxxxxxxxxxx +xxxxx: │ +│ .xxxxx. :xxxxxxxxxx .xxxxx. │ +│ xxxxx+ ;xxxxxxxx +xxxxx │ +│ xxxxx +xx. xxxxx. │ +│ xxxxx: .xxxxxxxx :xxxxx │ +│ xxxxx .xxxxxxxxxx xxxxx │ +│ xxxxx xxxxxxxxxxx xxxxx │ +│ xxxxx .xxxxxxxxxx xxxxx │ +│ xxxxx: .xxxxxxxx :xxxxx │ +│ .xxxxx ;xx. ... xxxxx. │ +│ xxxxx+ :xxxxxxxx +xxxxx │ +│ .xxxxx. :xxxxxxxxxx .xxxxx. │ +│ :xxxxx+ xxxxxxxxxxx ;xxxxx: │ +│ :xxxxxx xxxxxxxxxx xxxxxx: │ +│ xxxxxxx xxxxxxx; xxxxxxx │ +│ xxxxxxxx. .xxxxxxxx │ +│ xxxxxxxxxx xxxxxxxxxx │ +│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+ │ +│ ;xxxxxxxxxxxxxxxxxxxxxx; │ +│ .xxxxxxxxxxxxxx. │ +│ │ +╰────────────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────────────── Plone Addon ────────────────────────────────────╮ +│ Creating a new Plone Addon │ +╰────────────────────────────────────────────────────────────────────────────────────╯ + [1/7] Addon Title (Addon): + [2/7] A short description of your addon (A new addon for Plone): + [3/7] Author (Plone Community): + [4/7] Author E-mail (collective@plone.org): + [5/7] GitHub Username or Organization (collective): + [6/7] Python package name (collective.addon): + [7/7] Support headless Plone? + 1 - Yes + 2 - No + Choose from [1/2] (1): + -> Initialize Git repository +╭───────────────────────────── New addon was generated ──────────────────────────────╮ +│ │ +│ Addon │ +│ │ +│ Now, enter the repository run the code formatter with: │ +│ │ +│ make format │ +│ │ +│ start coding, and push to your organization. │ +│ │ +│ Sorry for the convenience, │ +│ The Plone Community. │ +│ │ +│ https://plone.org/ │ +╰────────────────────────────────────────────────────────────────────────────────────╯ +``` + + +## Install the project + +Change to your project directory. + +```shell +cd collective.addon +``` + +To install the project's dependencies, use the following command. + +```shell +make install +``` + +This will take a few minutes. +☕️ + +When the process completes successfully, it will exit with no message. + +```{include} /_inc/_install-pillow.md +``` + + +## Start Plone + +To start Plone, issue the following command. + +```shell +make start +``` + +The Plone backend server starts up and emits messages to the console. + +```console +2024-09-25 16:47:15,699 INFO [chameleon.config:39][MainThread] directory cache: //instance/var/cache. +2024-09-25 16:47:16,387 WARNING [ZODB.FileStorage:412][MainThread] Ignoring index for //instance/var/filestorage/Data.fs +2024-09-25 16:47:16,508 INFO [plone.restapi.patches:16][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB. +2024-09-25 16:47:17,018 INFO [plone.volto:23][MainThread] Aliasing collective.folderish classes to plone.volto classes. +2024-09-25 16:47:17,760 INFO [Zope:42][MainThread] Ready to handle requests +Starting server in PID 20912. +2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://[::1]:8080 +2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080 +``` + +You can stop the site with {kbd}`ctrl-c`. + + +## Create Classic UI Plone site + +While the Plone backend server is running, open a browser and visit the following URL. + +http://localhost:8080 + +```{image} /_static/plone-classic-ui-landing-page.png +:class: figure +:alt: Plone Classic UI landing page +``` + +Click the button {guilabel}`Create Classic UI Plone site` to do exactly that. + +Use the username and password of `admin` to authenticate. +You will be redirected to the Create a Plone site page. + +```{image} /_static/plone-classic-ui-site-page.png +:class: figure +:alt: Plone Classic UI site page +``` + +Enter values for {guilabel}`Path identifier`, {guilabel}`Title`, {guilabel}`Language`, and {guilabel}`Default timezone`. +The default values are usually good. + +Click the button {guilabel}`Create Plone site`. + +You will be redirected to the Plone site you just created. diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md new file mode 100644 index 000000000..2fcf7da48 --- /dev/null +++ b/docs/install/create-project-cookieplone.md @@ -0,0 +1,320 @@ +--- +myst: + html_meta: + "description": "Create a Plone project with the Volto frontend (development or pre-release)" + "property=og:description": "Create a Plone project with the Volto frontend (development or pre-release)" + "property=og:title": "Create a Plone project with the Volto frontend (development or pre-release)" + "keywords": "Plone, Plone 6, Volto, create, project, install, Cookieplone" +--- + + +(create-project-cookieplone-label)= + +# Create a project with Volto (development or pre-release) + +This chapter describes how you can create a web application using the latest **development release** version of Plone with **Volto 18 or later** for the frontend, while having full control over its development and deployment. + +```{seealso} +For other installation options, see {doc}`/install/index`. +``` + +```{versionadded} Volto 18.0.0-alpha.43 +{term}`Cookieplone` is now the method to create a Plone project with unstable versions of Volto, version 18.0.0-alpha.43 and above. +``` + + +## System requirements + +Plone 6 has both hardware requirements and software pre-requisites. + + +### Hardware requirements + +```{include} /_inc/_hardware-requirements.md +``` + +### Pre-requisites for installation + +```{include} ../volto/contributing/install-operating-system.md +``` + +- Python {SUPPORTED_PYTHON_VERSIONS} +- {term}`pipx` +- {term}`nvm` +- {term}`Node.js` LTS 20.x +- {term}`GNU make` +- {term}`Git` + + +#### Python + +```{include} /_inc/_install-python.md +``` + + +#### pipx + +Install {term}`pipx`. + +```shell +pip install pipx +``` + + +#### nvm + +```{include} ../volto/contributing/install-nvm.md +``` + + +#### Node.js + +```{include} ../volto/contributing/install-nodejs.md +``` + +3. Enable {term}`corepack` so that Node.js will install {term}`pnpm` as a package manager. + + ```shell + corepack enable + ``` + + +#### Make + +```{include} ../volto/contributing/install-make.md +``` + + +#### Git + +```{include} ../volto/contributing/install-git.md +``` + + +## Generate the project + +After satisfying the pre-requisites and having activated an LTS version of Node, +generate the project. + +```shell +pipx run cookieplone project +``` + +You will be presented with a series of prompts. +You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. +For ease of documentation, we will use the default values. + +```{tip} +See the cookiecutter's README for how to [Use options to avoid prompts](https://github.com/collective/cookieplone/?tab=readme-ov-file#use-options-to-avoid-prompts). +``` + +```{important} +For {guilabel}`Project Slug`, you must not use any of the Plone core package names listed in [`constraints.txt`](https://dist.plone.org/release/6.0-latest/constraints.txt). +Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the same package. +``` + +```console +% pipx run cookieplone project +╭──────────────────────────────── cookieplone ────────────────────────────────╮ +│ │ +│ .xxxxxxxxxxxxxx. │ +│ ;xxxxxxxxxxxxxxxxxxxxxx; │ +│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx; │ +│ xxxxxxxxxx xxxxxxxxxx │ +│ xxxxxxxx. .xxxxxxxx │ +│ xxxxxxx xxxxxxx: xxxxxxx │ +│ :xxxxxx xxxxxxxxxx xxxxxx: │ +│ :xxxxx+ xxxxxxxxxxx +xxxxx: │ +│ .xxxxx. :xxxxxxxxxx .xxxxx. │ +│ xxxxx+ ;xxxxxxxx +xxxxx │ +│ xxxxx +xx. xxxxx. │ +│ xxxxx: .xxxxxxxx :xxxxx │ +│ xxxxx .xxxxxxxxxx xxxxx │ +│ xxxxx xxxxxxxxxxx xxxxx │ +│ xxxxx .xxxxxxxxxx xxxxx │ +│ xxxxx: .xxxxxxxx :xxxxx │ +│ .xxxxx ;xx. ... xxxxx. │ +│ xxxxx+ :xxxxxxxx +xxxxx │ +│ .xxxxx. :xxxxxxxxxx .xxxxx. │ +│ :xxxxx+ xxxxxxxxxxx ;xxxxx: │ +│ :xxxxxx xxxxxxxxxx xxxxxx: │ +│ xxxxxxx xxxxxxx; xxxxxxx │ +│ xxxxxxxx. .xxxxxxxx │ +│ xxxxxxxxxx xxxxxxxxxx │ +│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+ │ +│ ;xxxxxxxxxxxxxxxxxxxxxx; │ +│ .xxxxxxxxxxxxxx. │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────╯ +You've downloaded /Users/stevepiercy/.cookiecutters/cookieplone-templates +before. Is it okay to delete and re-download it? [y/n] (y): +╭─────────────────────────────── Plone Project ───────────────────────────────╮ +│ Creating a new Plone Project │ +╰─────────────────────────────────────────────────────────────────────────────╯ + [1/17] Project Title (Project Title): + [2/17] Project Description (A new project using Plone 6.): + [3/17] Project Slug (Used for repository id) (project-title): + [4/17] Project URL (without protocol) (project-title.example.com): + [5/17] Author (Plone Foundation): + [6/17] Author E-mail (collective@plone.org): + [7/17] Should we use prerelease versions? (No): + [8/17] Plone Version (6.0.13): + [9/17] Volto Version (18.0.0-alpha.43): + [10/17] Python Package Name (project.title): + [11/17] Volto Addon Name (volto-project-title): + [12/17] Language + 1 - English + 2 - Deutsch + 3 - Español + 4 - Português (Brasil) + 5 - Nederlands + 6 - Suomi + Choose from [1/2/3/4/5/6] (1): + [13/17] GitHub or GitLab Username or Organization (collective): + [14/17] Container Registry + 1 - GitHub Container Registry + 2 - Docker Hub + 3 - GitLab + Choose from [1/2/3] (1): + [15/17] Should we setup a caching server? + 1 - Yes + 2 - No + Choose from [1/2] (1): + [16/17] Add Ansible playbooks? + 1 - Yes + 2 - No + Choose from [1/2] (1): + [17/17] Add GitHub Action to Deploy this project? + 1 - Yes + 2 - No + Choose from [1/2] (1): +╭───────────────────────── Project Title generation ──────────────────────────╮ +│ │ +│ Summary: │ +│ │ +│ - Plone version: 6.0.13 │ +│ - Volto version: 18.0.0-alpha.43 │ +│ - Output folder: │ +│ /project-title │ +│ │ +│ │ +╰─────────────────────────────────────────────────────────────────────────────╯ + -> Initialize Git repository + -> Setup Backend + -> Setup Frontend + -> Setup Cache + -> Setup Project Settings +╭───────────────────────── New project was generated ─────────────────────────╮ +│ │ +│ Project Title │ +│ │ +│ Now, code it, create a git repository, push to your organization. │ +│ │ +│ Sorry for the convenience, │ +│ The Plone Community. │ +│ │ +│ https://plone.org/ │ +╰─────────────────────────────────────────────────────────────────────────────╯ +``` + +## Install the project + +To work on your project, you need to install both the frontend and backend. + +Change your current working directory to {file}`project-title`. + +```shell +cd project-title +``` + +To install both the Plone backend and frontend, use the following command. + +```shell +make install +``` + +This will take a few minutes. +☕️ +First the backend, then the frontend will be installed. + +When the process completes successfully, it will exit with no message. + +```{include} /_inc/_install-pillow.md +``` + + +## Start Plone + +Plone 6 has two servers: one for the frontend, and one for the backend. +As such, we need to maintain two active shell sessions, one for each server, to start your Plone site. + + +### Start Plone backend + +In the currently open session, issue the following command. + +```shell +make backend-start +``` + +The Plone backend server starts up and emits messages to the console. + +```console +2024-09-25 16:47:15,699 INFO [chameleon.config:39][MainThread] directory cache: //backend/instance/var/cache. +2024-09-25 16:47:16,387 WARNING [ZODB.FileStorage:412][MainThread] Ignoring index for //backend/instance/var/filestorage/Data.fs +2024-09-25 16:47:16,508 INFO [plone.restapi.patches:16][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB. +2024-09-25 16:47:17,018 INFO [plone.volto:23][MainThread] Aliasing collective.folderish classes to plone.volto classes. +2024-09-25 16:47:17,760 INFO [Zope:42][MainThread] Ready to handle requests +Starting server in PID 20912. +2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://[::1]:8080 +2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080 +``` + + +### Start Plone frontend + +Create a second shell session in a new window. +Change your current working directory to {file}`project-title`. +Start the Plone frontend with the following command. + +```shell +make frontend-start +``` + +The Plone frontend server starts up and emits messages to the console, and should end with the following. + +```console +webpack 5.90.1 compiled successfully in 11004 ms +sswp> Handling Hot Module Reloading +Using volto.config.js in: //frontend/volto.config.js +✅ Server-side HMR Enabled! +Volto is running in SEAMLESS mode +Proxying API requests from http://localhost:3000/++api++ to http://localhost:8080/Plone +🎭 Volto started at 0.0.0.0:3000 🚀 +``` + +Note that the Plone frontend uses an internal proxy server to connect with the Plone backend. +Open a browser at the following URL to visit your Plone site. + +http://localhost:3000 + +You will see a page similar to the following. + +```{image} /_static/plone-home-page.png +:alt: Plone home page +:class: figure +``` + +Select the {guilabel}`Login` link to visit the login form, and enter the following credentials. + +- {guilabel}`Login name`: `admin` +- {guilabel}`Password`: `admin` + +```{image} /_static/plone-login-page.png +:alt: Plone login page +:class: figure +``` + +Now you can edit content or configure your Plone site. + +You can stop the site with {kbd}`ctrl-c`. diff --git a/docs/install/create-project.md b/docs/install/create-project.md index 396f8447a..db008515f 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -1,20 +1,22 @@ --- myst: html_meta: - "description": "Create a Plone project" - "property=og:description": "Create a Plone project" - "property=og:title": "Create a Plone project" - "keywords": "Plone, Plone 6, create, project, install, cookiecutter" + "description": "Create a Plone project with the Volto frontend (stable release)" + "property=og:description": "Create a Plone project with the Volto frontend (stable release)" + "property=og:title": "Create a Plone project with the Volto frontend (stable release)" + "keywords": "Plone, Plone 6, Volto, create, project, install, cookiecutter" --- (create-a-project-label)= -# Create a project +# Create a project with Volto (stable release) -This chapter describes how you can create a web application project using Plone, with full control over development and deployment. +This chapter describes how you can create a web application using the current **stable release** version of Plone with **Volto 17 or earlier** for the frontend, while having full control over its development and deployment. -If instead you want to contribute to a Plone package, see {doc}`/contributing/index`. +```{seealso} +For other installation options, see {doc}`/install/index`. +``` (install-packages-system-requirements-label)= @@ -28,25 +30,8 @@ Plone 6 has both hardware requirements and software pre-requisites. ### Hardware requirements -The hardware requirements below give a rough estimate of the minimum hardware setup needed for a Plone server. - -A single Plone installation is able to run many Plone sites. - -- Installation of the Plone backend and Classic UI frontend requires a minimum of 256 MB of RAM and 2GB of disk swap space. -- Installation of the Volto frontend requires a minimum of 2GB of RAM. -- After installation, running Plone requires a minimum of 256 MB RAM and 512 MB of disk swap space per Plone site. - 2 GB or more RAM per Plone site is recommended. -- Minimum 512 MB hard disk space is required. - 40 GB or more hard disk space is recommended. - - -````{warning} -{term}`Add-on` products and caching solutions may also increase RAM and disk swap space requirements. -To avoid RAM and disk swap limitations, we recommend either temporarily resizing your remote machine to accommodate the build, or build your images locally and upload them to an image store, such as [Docker Hub](https://hub.docker.com/) or [GitHub Packages](https://github.com/features/packages). -```{seealso} -[How much RAM is required to build a Volto front end?](https://community.plone.org/t/how-much-ram-is-required-to-build-a-volto-front-end/17949) and [Dealing with heap exhaustion while building Volto 17 on limited-RAM host](https://community.plone.org/t/dealing-with-heap-exhaustion-while-building-volto-17-on-limited-ram-host/18078). +```{include} /_inc/_hardware-requirements.md ``` -```` (install-packages-prerequisites-label)= @@ -71,9 +56,8 @@ To avoid RAM and disk swap limitations, we recommend either temporarily resizing #### Python -Installing Python is beyond the scope of this documentation. -However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. -Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. +```{include} /_inc/_install-python.md +``` (install-prerequisites-pipx-label)= @@ -91,39 +75,9 @@ pip install pipx #### nvm -The following terminal session commands use `bash` for the shell. -Adapt them for your flavor of shell. - -```{seealso} -See the [`nvm` install and update script documentation](https://github.com/nvm-sh/nvm#install--update-script). -For the `fish` shell, see [`nvm.fish`](https://github.com/jorgebucaran/nvm.fish). +```{include} ../volto/contributing/install-nvm.md ``` -1. Create your shell profile, if it does not exist. - - ```shell - touch ~/.bash_profile - ``` - -2. Download and run the `nvm` install and update script, and pipe it into `bash`. - - ```shell - curl -o- https://raw.githubusercontent.com/creationix/nvm/v{NVM_VERSION}/install.sh | bash - ``` - -3. Source your profile. - Alternatively close the session and open a new one. - - ```shell - source ~/.bash_profile - ``` - -4. Verify that the `nvm` version is that which you just installed or updated: - - ```shell - nvm --version - ``` - (install-prerequisites-nodejs-label)= @@ -353,6 +307,9 @@ First the backend, then the frontend will be installed. When the process completes successfully, it will exit with no message. +```{include} /_inc/_install-pillow.md +``` + ````{note} If you used a Plone core package name, then `make install` will return an error message such as the following. diff --git a/docs/install/index.md b/docs/install/index.md index 2cdb8af20..3f0091b15 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -11,17 +11,8 @@ myst: # Install -In this part of the documentation, you can find how to {ref}`try Plone ` or how to install Plone to either {doc}`Create a Plone project ` or {doc}`Contribute to a Plone package `. - - -(install-index-try-plone-label)= - -## Try a Plone demo - -Choose a version to demo. - -- [Plone 6 with Volto frontend](https://demo.plone.org/) -- [Plone 6 with Classic UI](https://classic.demo.plone.org/login?came_from=/en) +In this part of the documentation, you can find how to install Plone to either create a Plone project or contribute to a Plone package. +You can also {ref}`try a Plone demo `. (install-index-getting-started-label)= @@ -31,26 +22,30 @@ Choose a version to demo. Choose an option to get started with Plone. If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose. -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 +{doc}`create-project` +: This option is for developers who want to create a web application using the current **stable release** version of Plone with **Volto 17 or earlier** for the frontend. + +{doc}`create-project-classic-ui` +: This option is for developers who want to create a web application using the current **stable release** version of Plone with **Classic UI** for the frontend. -:::{grid-item-card} {octicon}`browser;1.5em;sd-mr-1` Create a project -:link: create-project -:link-type: doc +{doc}`create-project-cookieplone` +: This option is for developers who want to create a web application using the latest **development release** version of Plone with **Volto 18 or later** for the frontend. + The "development" version also means "pre-release", and includes alpha and beta versions and release candidates. + It allows developers to work with the cutting edge of Plone. + A development version is not stable, and features may change with little notice. -This option is for developers who want to create a web application using Plone. -See {doc}`create-project`. -::: +{doc}`Contribute to a Plone package ` +: This option is for developers who want to contribute to Plone and its packages. -:::{grid-item-card} {octicon}`repo-push;1.5em;sd-mr-1` Contribute to a Plone package -:link: plone:contributing/index -:link-type: doc -This option is for developers who want to contribute to Plone and its packages. -See {doc}`plone:contributing/index`. -::: +(install-index-try-plone-label)= + +## Try a Plone demo -:::: +Choose a version to demo. + +- [Plone 6 with Volto frontend](https://demo.plone.org/) +- [Plone 6 with Classic UI](https://classic.demo.plone.org/login?came_from=/en) ```{toctree} @@ -58,6 +53,8 @@ See {doc}`plone:contributing/index`. :hidden: true create-project +create-project-classic-ui +create-project-cookieplone manage-add-ons-packages containers/index ```