Start Admin Guide, revamp install/getting started

docs/admin-guide/add-ons.md

@@ -0,0 +1,204 @@
+---
+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, addon, add-on, package, plugin, extension, install"
+---
+
+(install-plone-addons-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. See {doc}`/volto/addons/index`.
+```
+
+## with Cookieplone
+
+Use the following instructions if you installed Plone with Cookieplone or `cookiecutter-plone-starter`.
+
+### Install an add-on
+
+Add a line with the name of your add-on in `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 ensures that it won't accidentally get upgraded in the future.
+```
+
+Also add the add-on to `zcml_package_includes` in {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:
+
+```shell
+make backend-build
+```
+
+```{note}
+If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.`
+```
+
+Now restart the backend.
+
+In your web browser, and assuming you are currently logged in as `admin`, 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 `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 to not pin a version, to make sure we use the version that's currently available in the source control system.
+```
+
+Also add the add-on to `zcml_package_includes` in {file}`backend/instance.yaml` to make sure its configuration will be loaded:
+
+```yaml
+default_context:
+    zcml_package_includes: project_title, collective.easyform
+```
+
+Finally, add the package's source to {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:
+
+```shell
+make backend-build
+```
+
+```{note}
+If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.`
+```
+
+Now restart the backend.
+
+In your web browser, and assuming you are currently logged in as `admin`, 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 {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 ensures that it won't accidentally get upgraded in the future.
+```
+
+To actually download and install the new add-on, run:
+
+```shell
+bin/buildout
+```
+
+Then restart your instance.
+
+### Install an add-on from source
+
+An add-on can be installed from a source control system such as GitHub.
+
+Update {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:
+
+```shell
+bin/buildout
+```
+
+Then restart your instance.
+
+```{seealso}
+This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
+```

docs/admin-guide/configure-zope.md

@@ -0,0 +1,33 @@
+---
+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, cookiecutter-zope-instance"
+---
+
+(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 filestorage, relation database, ZEO, and so on
+* ports
+* threads
+* cache
+* logging
+* debugging and profiling for development
+
+## with 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).
+
+## with 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,43 @@
+---
+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
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Deploy
+
+/install/containers/index
+```

docs/admin-guide/install-buildout.md

@@ -0,0 +1,105 @@
+---
+myst:
+  html_meta:
+    "description": "Install Plone with Buildout"
+    "property=og:description": "Install Plone with Buildout"
+    "property=og:title": "Install Plone with Buildout"
+    "keywords": "Plone 6, install, Classic UI, buildout"
+---
+
+(install-buildout-label)=
+
+# Install Plone with Buildout
+
+This chapter describes how you can install Plone using {term}`Buildout`.
+
+This is one way to install Plone with the Classic UI.
+Using Buildout will be the most familiar approach for admins who have experience with Plone 3, 4, or 5.
+
+```{seealso}
+For other installation options, see {ref}`get-started-install-label`.
+```
+
+(install-buildout-prerequisites)=
+
+## Prerequisites
+
+- Python 3.10 or greater
+
+On Debian-based Linux systems you can install Python with the following command:
+
+```shell
+sudo apt install python3.12 python3.12-dev python3.12-venv
+```
+
+## Installation
+
+Select a directory of your choice:
+
+```shell
+mkdir -p /opt/plone && cd /opt/plone
+```
+
+Create a Python virtual environment:
+
+```shell
+python3 -m 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
+```
+
+Create a `buildout.cfg` file in your directory with the following contents:
+
+```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
+```
+
+Run buildout:
+
+```shell
+bin/buildout
+```
+
+## Run Plone in foreground mode
+
+Start the instance for a quick test in foreground mode:
+
+```shell
+bin/instance fg
+```
+
+Your instance starts in foreground mode, which is only advisable for troubleshooting or for local demonstration purposes.
+
+Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site**.
+
+## Start Plone as a background service
+
+Start the instance:
+
+```shell
+bin/instance start
+```
+
+## Stop Plone as a background service
+
+Stop the instance:
+
+```shell
+bin/instance stop
+```