From 4daa66cdbc0bc2e3ae2bbcf264814ea3500550ed Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 6 Nov 2024 18:25:24 -0800 Subject: [PATCH 01/12] Simplify the introductory container installation docs (#1729) It's a best practice to run Volto in seamless mode, where the API is served at the same domain with the /++api++ prefix. This avoids complications with browser cross-origin restrictions when the browser accesses the backend directly at a different domain. So, we should show this best practice here. The current example sets RAZZLE_API_PATH, because the default is http://localhost:8080/Plone which does not work inside a container. But, setting RAZZLE_API_PATH also stops using the best practice of seamless mode. We can avoid this by setting RAZZLE_DEV_PROXY_API_PATH instead. (Future improvement: make Volto recognize when it is running in a container, so that it can use http://host.docker.internal:8080/Plone as the default API path instead of localhost. Then it would not be necessary to set RAZZLE_DEV_PROXY_API_PATH here.) Co-authored-by: David Glick --- docs/install/containers/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index 0d75813d8..6edf7bcb0 100644 --- a/docs/install/containers/index.md +++ b/docs/install/containers/index.md @@ -66,13 +66,13 @@ Docker Desktop includes all Docker tools. First start the Plone Backend, naming it `plone6-backend` and creating a site with its default configuration, using the following command. ```shell -docker run --name plone6-backend -e SITE=Plone -e CORS_ALLOW_ORIGIN='*' -d -p 8080:8080 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} +docker run --name plone6-backend -e SITE=Plone -d -p 8080:8080 plone/plone-backend:{PLONE_BACKEND_MINOR_VERSION} ``` Now start the Plone Frontend, linking it to the `plone6-backend`: ```shell -docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_API_PATH=http://localhost:8080/Plone -e RAZZLE_INTERNAL_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest +docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest ``` From cdd32bac106d4c588c71c3fe2a2fc49678221645 Mon Sep 17 00:00:00 2001 From: Maik Derstappen Date: Thu, 7 Nov 2024 05:54:51 +0200 Subject: [PATCH 02/12] Improve install docs (#1760) * rm deployment from admin guide description, as deployment has it's own chapter * correct venv creation, never mix venv and other configation files * Update docs/admin-guide/run-plone.md Co-authored-by: David Glick * Apply suggestions from code review --------- Co-authored-by: David Glick Co-authored-by: Steve Piercy --- docs/admin-guide/index.md | 2 +- docs/admin-guide/install-buildout.md | 15 ++++++++++++--- docs/admin-guide/install-pip.md | 6 +++--- docs/admin-guide/run-plone.md | 1 + 4 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index cf15440e2..cfd1fd152 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -11,7 +11,7 @@ myst: # Admin guide -In this part of the documentation, you can find how to install, operate, configure, and deploy Plone. +In this part of the documentation, you can find how to install, operate, and configure Plone. ```{toctree} diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index f0f87cc2e..2cd5c586f 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -25,7 +25,7 @@ For other installation options, see {ref}`get-started-install-label`. ## Prerequisites for installation - For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} -% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". +% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". % - For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} @@ -47,15 +47,17 @@ cd /plone Create a Python virtual environment. ```shell -python3 -m venv . +python3 -m venv venv ``` Install the minimal Python packages needed in order to run Buildout. ```shell -bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt +venv/bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt ``` + + Create a {file}`buildout.cfg` file in your directory with the following contents. ```cfg @@ -75,6 +77,12 @@ eggs = Plone ``` +Use Buildout's [`bootstrap` command](https://www.buildout.org/en/latest/topics/bootstrapping.html) to install a local `buildout` script in the {file}`bin` directory. + +```shell +venv/bin/buildout bootstrap +``` + Run Buildout. ```shell @@ -83,6 +91,7 @@ bin/buildout This may take a few minutes. +Whenever you change the Buildout configuration, run `./bin/buildout` again. ## Start Plone in foreground mode diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md index 62ede6906..cb8aad8de 100644 --- a/docs/admin-guide/install-pip.md +++ b/docs/admin-guide/install-pip.md @@ -25,7 +25,7 @@ For other installation options, see {ref}`get-started-install-label`. ## Prerequisites for installation - For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} -% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". +% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". % - For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} @@ -47,13 +47,13 @@ cd /plone Create a Python virtual environment. ```shell -python3 -m venv . +python3 -m venv venv ``` Install Plone and a helper package, {term}`pipx`. ```shell -bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx +venv/bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx ``` diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md index d90e363be..66eb6ed30 100644 --- a/docs/admin-guide/run-plone.md +++ b/docs/admin-guide/run-plone.md @@ -19,6 +19,7 @@ There are different commands to run Plone, depending on which method you used to Running Plone in foreground mode will show output in the terminal. This is recommended while developing a Plone site. +The command you use depends on the installation method you used. Cookieplone: : ```shell From e7751efd26c8d6146a4f7089fc8284cde2de7ac2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 6 Nov 2024 21:44:58 -0800 Subject: [PATCH 03/12] Update tip submodules/volto --- submodules/volto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/volto b/submodules/volto index 5d08348bf..5c0dd143f 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 5d08348bf443a67241a995e6c917eadf6d81b1fc +Subproject commit 5c0dd143fca3b0c6be46e384eefbda12be06b536 From 063673af3f02a6427fbb0895e08d82a559a7b736 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 7 Nov 2024 00:09:14 -0800 Subject: [PATCH 04/12] Add anchors for linking from Training via Intersphinx (#1762) Ping @nileshgulia1 --- docs/install/create-project-cookieplone.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 465bfbfdc..db864f1ba 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -33,11 +33,16 @@ For other installation options, see {ref}`get-started-install-label`. Plone 6 has both hardware requirements and software prerequisites. +(create-project-cookieplone-hardware-requirements-label)= + ### Hardware requirements ```{include} /_inc/_hardware-requirements.md ``` + +(create-project-cookieplone-prerequisites-for-installation-label)= + ### Prerequisites for installation ```{include} ../volto/contributing/install-operating-system.md From 4c6f65d0da8410f1af0122c200ac42fadafed410 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 7 Nov 2024 00:59:01 -0800 Subject: [PATCH 05/12] Add anchors for linking from Training via Intersphinx (#1763) Ping @nileshgulia1 --- docs/install/create-project-cookieplone.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index db864f1ba..306412a8e 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -101,6 +101,8 @@ pip install pipx ``` +(create-project-cookieplone-generate-the-project-label)= + ## Generate the project After satisfying the prerequisites and having activated an LTS version of Node, From a0993fefba3b1d16ad4042d56bfaa512fee0cd01 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 7 Nov 2024 03:32:46 -0800 Subject: [PATCH 06/12] Fix Docker Desktop install link redirects (#1765) --- docs/install/containers/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index 6edf7bcb0..52aa0d809 100644 --- a/docs/install/containers/index.md +++ b/docs/install/containers/index.md @@ -45,9 +45,9 @@ Although there are many container engine tools for developing, managing, and run The system requirements include those required by Docker itself. -- [Linux](https://docs.docker.com/desktop/install/linux/) -- [macOS](https://docs.docker.com/desktop/install/mac-install/) -- [Windows](https://docs.docker.com/desktop/install/windows-install/) +- [Linux](https://docs.docker.com/desktop/setup/install/linux/) +- [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) +- [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) Plone 6 itself requires memory and disk space in addition to those of Docker alone. See its {ref}`install-packages-hardware-requirements-label`. From 1b5a9dc975e8343ba0bd76e56b957205c1747a24 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 7 Nov 2024 04:39:31 -0800 Subject: [PATCH 07/12] Add content for Backend > Search (#1764) Closes #281 @gforcada @jensens --- docs/backend/search.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/backend/search.md b/docs/backend/search.md index 318453e55..dbe73570d 100644 --- a/docs/backend/search.md +++ b/docs/backend/search.md @@ -1,16 +1,30 @@ --- myst: html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" + "description": "How to index and search content in Plone" + "property=og:description": "How to index and search content in Plone" + "property=og:title": "Search" + "keywords": "Plone, search, index, querystring, catalog" --- (backend-search-label)= # Search +To index and search content in Plone, see the Plone 5 documentation {doc}`/develop/plone/searching_and_indexing/index`. + +Alternatively, you can integrate any open source search engine with your Plone site. + +- [Solr](https://solr.apache.org/) - See the add-on [`collective.solr`](https://github.com/collective/collective.solr) and its [documentation](https://collectivesolr.readthedocs.io/en/latest/). +- [`collective.elasticsearch`](https://github.com/collective/collective.elasticsearch) +- [`collective.elastic.plone`](https://github.com/collective/collective.elastic.plone) + +You can find a comprehensive list of search options in [Awesome Plone - Searching and Categorizing](https://github.com/collective/awesome-plone?tab=readme-ov-file#searching-and-categorizing) + + +```{todo} +Help us [Migrate content from v5 "Queries, Search And Indexing" #1730](https://github.com/plone/documentation/issues/1730). +``` (backend-search-catalog-label)= From 5f09714b5749d55b2935858a0599c8776a9b882f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 8 Nov 2024 03:51:51 -0800 Subject: [PATCH 08/12] Fix reference to Plone 5 docs (#1767) --- docs/backend/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/search.md b/docs/backend/search.md index dbe73570d..5e25aadc2 100644 --- a/docs/backend/search.md +++ b/docs/backend/search.md @@ -11,7 +11,7 @@ myst: # Search -To index and search content in Plone, see the Plone 5 documentation {doc}`/develop/plone/searching_and_indexing/index`. +To index and search content in Plone, see the Plone 5 documentation {doc}`plone5:develop/plone/searching_and_indexing/index`. Alternatively, you can integrate any open source search engine with your Plone site. From 4812700c18bd16a478c387f0917a2d96ee92bfbd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 8 Nov 2024 03:53:09 -0800 Subject: [PATCH 09/12] Update tip submodules/volto --- submodules/volto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/volto b/submodules/volto index 5c0dd143f..4aecd1c86 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 5c0dd143fca3b0c6be46e384eefbda12be06b536 +Subproject commit 4aecd1c862f9a2ff42261f3dcc656f287953cedd From 50e4c5fe7a04beb9b4c7896188cf35da29c1ab34 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Nov 2024 01:29:02 -0800 Subject: [PATCH 10/12] Update tips submodules/plone.restapi submodules/volto --- submodules/plone.restapi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/plone.restapi b/submodules/plone.restapi index 9f0feffad..4f3bb4f1c 160000 --- a/submodules/plone.restapi +++ b/submodules/plone.restapi @@ -1 +1 @@ -Subproject commit 9f0feffad288f18e5fa3d3f63094614971d1d164 +Subproject commit 4f3bb4f1c656295f609a9aaea4540325d1b55b8e From 13caea4667e8e7ab64ce908aaf1101c6d0b99ad6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Nov 2024 03:53:58 -0800 Subject: [PATCH 11/12] Move Python virtual environment into venv from root (#1769) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Move Python virtual environment into venv from root `--clear` is the recommended way to wipe and recreate a clean virtual environment. `python3 -m venv venv --clear` will purge files and directories, such as `.git` and `.my_special_config`, from the current directory. This would be Very Bad™. - Enhance `make distclean` such that it cleans both the docs directory and the virtual environment, then recreates the virtual environment and installs requirements into it. This is useful when your project gets confused about what exactly is in your virtual environment - Update internal Makefile command. No change to user commands. Credit to @mrtango * Add to .gitignore --- .gitignore | 6 +----- Makefile | 32 +++++++++++++++++++------------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/.gitignore b/.gitignore index 82863e71d..7944bc77e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,7 @@ # Dependencies -/bin -/include -/lib -/lib64 +/venv # Generated files -pyvenv.cfg /_build /styles/Microsoft /share diff --git a/Makefile b/Makefile index 98e33474b..6d54cdb42 100644 --- a/Makefile +++ b/Makefile @@ -5,10 +5,11 @@ SHELL = bash # You can set these variables from the command line. SPHINXOPTS ?= PAPER ?= +VALEOPTS ?= # Internal variables. -SPHINXBUILD = "$(realpath bin/sphinx-build)" -SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)" +SPHINXBUILD = "$(realpath venv/bin/sphinx-build)" +SPHINXAUTOBUILD = "$(realpath venv/bin/sphinx-autobuild)" DOCS_DIR = ./docs/ BUILDDIR = ../_build PAPEROPT_a4 = -D latex_paper_size=a4 @@ -29,20 +30,25 @@ clean: ## Clean docs build directory cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ .PHONY: distclean -distclean: ## Clean docs build directory and Python virtual environment +distclean: ## Clean docs build directory and Python virtual environment, then install requirements cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ - rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg - + python3 -m venv venv --clear + venv/bin/pip install -r requirements-initial.txt + venv/bin/pip install -r requirements.txt + @echo + @echo "Installation of requirements completed." -bin/python: - python3 -m venv . - bin/pip install -r requirements-initial.txt - bin/pip install -r requirements.txt +venv/bin/python: ## Setup up Python virtual environment and install requirements + python3 -m venv venv + venv/bin/pip install -r requirements-initial.txt + venv/bin/pip install -r requirements.txt + @echo + @echo "Installation of requirements completed." docs/plone.api: git submodule init; \ git submodule update; \ - bin/pip install -e submodules/plone.api/"[test]"; \ + venv/bin/pip install -e submodules/plone.api/"[test]"; \ ln -s ../submodules/plone.api/docs ./docs/plone.api @echo @echo "Documentation of plone.api initialized." @@ -62,7 +68,7 @@ docs/volto: @echo "Documentation of volto initialized." .PHONY: deps -deps: bin/python docs/volto docs/plone.restapi docs/plone.api ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files. +deps: venv/bin/python docs/volto docs/plone.restapi docs/plone.api ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files. .PHONY: html @@ -196,8 +202,8 @@ linkcheckbroken: deps ## Run linkcheck and show only broken links .PHONY: vale vale: deps ## Run Vale style, grammar, and spell checks - bin/vale sync - bin/vale --no-wrap $(VALEFILES) + venv/bin/vale sync + venv/bin/vale --no-wrap $(VALEOPTS) $(VALEFILES) @echo @echo "Vale is finished; look for any errors in the above output." From 7f75e8bbd4564b912bbbf13529df8b96b7188849 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 13 Nov 2024 01:16:37 -0800 Subject: [PATCH 12/12] Add comparison between Buildout and pip installation tools for Classic UI (#1766) --- .../conceptual-guides/compare-buildout-pip.md | 38 +++++++++++++++++++ docs/glossary.md | 3 ++ docs/install/index.md | 2 + 3 files changed, 43 insertions(+) create mode 100644 docs/conceptual-guides/compare-buildout-pip.md diff --git a/docs/conceptual-guides/compare-buildout-pip.md b/docs/conceptual-guides/compare-buildout-pip.md new file mode 100644 index 000000000..af770a706 --- /dev/null +++ b/docs/conceptual-guides/compare-buildout-pip.md @@ -0,0 +1,38 @@ +--- +myst: + html_meta: + "description": "Compare Plone Classic UI's installation tools, Buildout and pip" + "property=og:description": "Compare Plone Classic UI's installation tools, Buildout and pip" + "property=og:title": "Compare Buildout and pip" + "keywords": "Plone 6, Conceptual guides, Classic UI, Buildout, pip, install" +--- + +# Compare Buildout and pip + +This guide explains the differences between two tools, {term}`Buildout` and {term}`pip`, to install Plone and its Classic UI user interface, helping to inform your choice when developing your new project in Plone. + +The choice of installation tool has implications for admins and developers. + +````{grid} 1 1 1 2 +:gutter: 1 +:margin: 0 +:padding: 0 + +```{grid-item-card} Buildout +- You can create recipes to automate development and production installations. +- Maintained and used primarily by the small Plone community. +- May have problems resolving dependencies when a new pip or setuptools version is released. +- Source checkouts managed through {term}`mr.developer`. +``` + +```{grid-item-card} pip +- Installs or uninstalls packages only. +- Maintained and used by the large Python community. +- Changes in dependency resolution are well-documented. +- Source checkouts managed through {term}`mxdev`. +``` +```` + +```{seealso} +[Proposal: Use pip constraints as canonical version location #3670](https://github.com/plone/Products.CMFPlone/issues/3670) +``` \ No newline at end of file diff --git a/docs/glossary.md b/docs/glossary.md index ed4b20897..83da720e1 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -296,6 +296,9 @@ TC39 They established a [process](https://tc39.es/process-document/) where the proposals are discussed, developed, and eventually approved (or dropped). The process has five Stages (0 to 4) where reaching the Stage 4 means the proposal is finished, and it becomes part of the JavaScript specification. +`mr.developer` + [`mr.developer`](https://pypi.org/project/mr.developer/) is a {term}`Buildout` extension that makes it easy to work with buildouts containing lots of packages, where you only want to develop a few of them. + `mrs-developer` Also called "missdev", a tool similar to buildout's `mr.developer`. It automatically downloads and keeps up to date copies of software and add-ons under development based on definitions stored in `mrs.developer.json`. diff --git a/docs/install/index.md b/docs/install/index.md index f3218e913..817999afd 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -41,6 +41,8 @@ https://demo.plone.org/ First, choose a Plone user interface, or frontend. You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI. +If you choose Classic UI, then you can read {doc}`/conceptual-guides/compare-buildout-pip` to help inform your choice between Buildout and pip for an installation method. + Then choose one of the following installation methods. If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.