Start Admin Guide, revamp install/getting started

docs/_inc/_create-classic-ui-instance.md

@@ -0,0 +1,15 @@
+
+Your instance starts in foreground mode.
+This should be used only for troubleshooting or local demonstration purposes.
+
+Now you can visit `http://localhost:8080` in your browser.
+Click the button {guilabel}`Create Classic UI Plone site`.
+
+Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`.
+
+Enter values in the form, and click the button {guilabel}`Create Plone Site`.
+
+You will be redirected to your new Classic UI Plone site.
+
+To stop the Plone instance in foreground mode, type {kbd}`ctrl-c`.
+

docs/_inc/_install-python-plone60.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_PLONE60}.
+
+Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.

docs/_inc/_install-python.md → docs/_inc/_install-python-plone61.md

@@ -1,6 +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 {SUPPORTED_PYTHON_VERSIONS_PLONE61}.
 
-Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.
+Plone 6.1 requires Python version 3.10, 3.11, or 3.12.

docs/admin-guide/add-ons.md

@@ -0,0 +1,226 @@
+---
+myst:
+  html_meta:
+    "description": "Install Plone add-ons"
+    "property=og:description": "Install Plone add-ons"
+    "property=og:title": "Install Plone add-ons"
+    "keywords": "Plone 6, add-on, package, plugin, extension, install"
+---
+
+(install-plone-add-ons-label)=
+
+# Install Plone add-ons
+
+This chapter explains how to install {term}`add-ons <add-on>` as Python packages to extend the functionality of the Plone backend or Classic UI.
+
+```{note}
+The Volto frontend has its own system of add-ons using Node.js packages.
+% TODO: update the following link after https://github.com/plone/volto/pull/6397 is merged to point to `/development/add-ons/index`.
+See {doc}`/volto/addons/index`.
+```
+
+
+## Cookieplone
+
+Use the following instructions if you installed Plone with either Cookieplone or `cookiecutter-plone-starter`.
+
+
+### Install an add-on
+
+Add a line with the name of your add-on in the file {file}`backend/requirements.txt`.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+
+```
+collective.easyform==4.2.1
+```
+
+```{tip}
+Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
+```
+
+Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.
+
+```yaml
+default_context:
+    zcml_package_includes: project_title, collective.easyform
+```
+
+Stop the backend with {kbd}`ctrl-c`.
+
+To actually download and install the new add-on, run the following command.
+
+```shell
+make backend-build
+```
+
+```{note}
+If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.
+```
+
+Now restart the backend.
+
+```{seealso}
+{doc}`run-plone`
+```
+
+In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.
+
+Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on.
+
+Some add-ons have configuration options.
+To configure such add-ons, return to the {guilabel}`Site Setup` control panel.
+At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed.
+
+
+### Install an add-on from source
+
+An add-on can be installed from a source control system such as GitHub.
+
+Add a line with the name of your add-on in the file {file}`backend/requirements.txt`.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+
+```
+collective.easyform
+```
+
+```{note}
+When installing an add-on from source, it's best not to pin a version.
+This way you always get the version that's currently available in the source control system.
+```
+
+Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
+
+```yaml
+default_context:
+    zcml_package_includes: project_title, collective.easyform
+```
+
+Finally, add the package's source to the file {file}`mx.ini`.
+
+```cfg
+[collective.easyform]
+url=git@github.com:collective/collective.easyform.git
+branch=dev-branch-name
+extras=test
+```
+
+```{seealso}
+The {file}`mx.ini` file configures a tool called {term}`mxdev`.
+See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information.
+```
+
+Stop the backend with {kbd}`ctrl-c`.
+
+To actually download and install the new add-on, run the following command.
+
+```shell
+make backend-build
+```
+
+```{note}
+If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.
+```
+
+Now restart the backend.
+
+```{seealso}
+{doc}`run-plone`
+```
+
+In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.
+An upgrade step might need to be performed in the Plone control panel.
+Follow the upgrade information, if present.
+Else click the {guilabel}`Install` button to complete installation of the add-on.
+
+
+## with Buildout
+
+Use the following instructions if you installed Plone with Buildout.
+
+### Install an add-on
+
+Update the file {file}`buildout.cfg`.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+
+```cfg
+[buildout]
+extends =
+    https://dist.plone.org/release/6-latest/versions.cfg
+
+parts =
+    instance
+
+[instance]
+recipe = plone.recipe.zope2instance
+user = admin:admin
+http-address = 8080
+eggs =
+    Plone
+    collective.easyform
+
+[versions]
+collective.easyform = 4.2.1
+```
+
+```{tip}
+Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
+```
+
+To actually download and install the new add-on, run the following command.
+
+```shell
+bin/buildout
+```
+
+Then restart your instance.
+
+```{seealso}
+{doc}`run-plone`
+```
+
+
+### Install an add-on from source
+
+You can install an add-on from a source control system such as GitHub.
+
+Update the file {file}`buildout.cfg`.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+
+```cfg
+[buildout]
+extends =
+    https://dist.plone.org/release/6-latest/versions.cfg
+extensions = mr.developer
+auto-checkout =
+    collective.easyform
+
+parts =
+    instance
+
+[instance]
+recipe = plone.recipe.zope2instance
+user = admin:admin
+http-address = 8080
+eggs =
+    Plone
+    collective.easyform
+
+[sources]
+collective.easyform = git https://github.com/collective/collective.easyform.git
+```
+
+To actually download and install the new add-on, run the following command.
+
+```shell
+bin/buildout
+```
+
+Then restart your instance.
+
+```{seealso}
+{doc}`run-plone`
+```
+
+```{seealso}
+This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
+```

docs/admin-guide/configure-zope.md

@@ -0,0 +1,35 @@
+---
+myst:
+  html_meta:
+    "description": "Configure Zope options"
+    "property=og:description": "Configure Zope options"
+    "property=og:title": "Configure Zope"
+    "keywords": "Plone 6, Zope, instance, app server, config, Cookieplone, Buildout, pip, cookiecutter-plone-starter, cookiecutter-zope-instance, plone.recipe.zope2instance"
+---
+
+(configure-zope-label)=
+
+# Configure Zope
+
+Plone runs in an application server called {term}`Zope`.
+
+You can configure your Zope instance's options, including the following.
+
+-   persistent storage: blobs, direct file storage, relational database, ZEO, and other storage mechanisms
+-   ports
+-   threads
+-   cache
+-   logging
+-   debugging and profiling for development
+
+
+## Cookieplone
+
+If you installed Plone using Cookieplone, `cookiecutter-plone-starter`, or pip, then Zope is configured using {term}`cookiecutter-zope-instance`.
+For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s README](https://github.com/plone/cookiecutter-zope-instance#readme).
+
+
+## Buildout
+
+If you installed Plone using Buildout, then Zope is configured using `plone.recipe.zope2instance`.
+For a complete list of features, usage, and options, read [`plone.recipe.zope2instance`'s README](https://pypi.org/project/plone.recipe.zope2instance/).

docs/admin-guide/index.md

@@ -0,0 +1,47 @@
+---
+myst:
+  html_meta:
+    "description": "How to install, operate, configure, and deploy Plone 6"
+    "property=og:description": "How to install, operate, configure, and deploy Plone 6"
+    "property=og:title": "Admin guide"
+    "keywords": "Plone 6, admin, install, configuration, deploy"
+---
+
+(admin-index-label)=
+
+# Admin guide
+
+In this part of the documentation, you can find how to install, operate, configure, and deploy Plone.
+
+
+```{toctree}
+:caption: Install
+:maxdepth: 1
+
+/install/create-project-cookieplone
+install-buildout
+install-pip
+/install/create-project
+```
+
+```{toctree}
+:caption: Operate
+:maxdepth: 1
+
+run-plone
+configure-zope
+add-ons
+override-core
+/upgrade/index
+```
+% TODO: uncomment and add the following link to the Operate toctree when https://github.com/plone/volto/pull/6397 is merged.
+% https://volto--6397.org.readthedocs.build/development/add-ons/install-an-add-on.html
+% /volto/development/add-ons/index
+
+
+```{toctree}
+:maxdepth: 1
+:caption: Deploy
+
+/install/containers/index
+```