Skip to content

Commit 590de88

Browse files
davisaglidavisagli
authored
Merge pull request #1746 from plone/admin-guide
Start Admin Guide, revamp install/getting started
2 parents bc68a37 + 52e2cd9 commit 590de88

28 files changed

+931
-666
lines changed

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
2+
Your instance starts in foreground mode.
3+
This should be used only for troubleshooting or local demonstration purposes.
4+
5+
Now you can visit `http://localhost:8080` in your browser.
6+
Click the button {guilabel}`Create Classic UI Plone site`.
7+
8+
Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`.
9+
10+
Enter values in the form, and click the button {guilabel}`Create Plone Site`.
11+
12+
You will be redirected to your new Classic UI Plone site.
13+
14+
To stop the Plone instance in foreground mode, type {kbd}`ctrl-c`.
15+

‎docs/_inc/_install-python-plone60.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Installing Python is beyond the scope of this documentation.
2+
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.
3+
% TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes.
4+
% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}.
5+
6+
Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.

‎docs/_inc/_install-python.md renamed to ‎docs/_inc/_install-python-plone61.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Installing Python is beyond the scope of this documentation.
22
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.
33
% TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes.
4-
% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}.
4+
% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}.
55

6-
Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.
6+
Plone 6.1 requires Python version 3.10, 3.11, or 3.12.

‎docs/admin-guide/add-ons.md

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "Install Plone add-ons"
5+
"property=og:description": "Install Plone add-ons"
6+
"property=og:title": "Install Plone add-ons"
7+
"keywords": "Plone 6, add-on, package, plugin, extension, install"
8+
---
9+
10+
(install-plone-add-ons-label)=
11+
12+
# Install Plone add-ons
13+
14+
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.
15+
16+
```{note}
17+
The Volto frontend has its own system of add-ons using Node.js packages.
18+
% TODO: update the following link after https://github.com/plone/volto/pull/6397 is merged to point to `/development/add-ons/index`.
19+
See {doc}`/volto/addons/index`.
20+
```
21+
22+
23+
## Cookieplone
24+
25+
Use the following instructions if you installed Plone with either Cookieplone or `cookiecutter-plone-starter`.
26+
27+
28+
### Install an add-on
29+
30+
Add a line with the name of your add-on in the file {file}`backend/requirements.txt`.
31+
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
32+
33+
```
34+
collective.easyform==4.2.1
35+
```
36+
37+
```{tip}
38+
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
39+
```
40+
41+
Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.
42+
43+
```yaml
44+
default_context:
45+
zcml_package_includes: project_title, collective.easyform
46+
```
47+
48+
Stop the backend with {kbd}`ctrl-c`.
49+
50+
To actually download and install the new add-on, run the following command.
51+
52+
```shell
53+
make backend-build
54+
```
55+
56+
```{note}
57+
If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.
58+
```
59+
60+
Now restart the backend.
61+
62+
```{seealso}
63+
{doc}`run-plone`
64+
```
65+
66+
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.
67+
68+
Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on.
69+
70+
Some add-ons have configuration options.
71+
To configure such add-ons, return to the {guilabel}`Site Setup` control panel.
72+
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.
73+
74+
75+
### Install an add-on from source
76+
77+
An add-on can be installed from a source control system such as GitHub.
78+
79+
Add a line with the name of your add-on in the file {file}`backend/requirements.txt`.
80+
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
81+
82+
```
83+
collective.easyform
84+
```
85+
86+
```{note}
87+
When installing an add-on from source, it's best not to pin a version.
88+
This way you always get the version that's currently available in the source control system.
89+
```
90+
91+
Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
92+
93+
```yaml
94+
default_context:
95+
zcml_package_includes: project_title, collective.easyform
96+
```
97+
98+
Finally, add the package's source to the file {file}`mx.ini`.
99+
100+
```cfg
101+
[collective.easyform]
102+
url=git@github.com:collective/collective.easyform.git
103+
branch=dev-branch-name
104+
extras=test
105+
```
106+
107+
```{seealso}
108+
The {file}`mx.ini` file configures a tool called {term}`mxdev`.
109+
See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information.
110+
```
111+
112+
Stop the backend with {kbd}`ctrl-c`.
113+
114+
To actually download and install the new add-on, run the following command.
115+
116+
```shell
117+
make backend-build
118+
```
119+
120+
```{note}
121+
If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.
122+
```
123+
124+
Now restart the backend.
125+
126+
```{seealso}
127+
{doc}`run-plone`
128+
```
129+
130+
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.
131+
An upgrade step might need to be performed in the Plone control panel.
132+
Follow the upgrade information, if present.
133+
Else click the {guilabel}`Install` button to complete installation of the add-on.
134+
135+
136+
## with Buildout
137+
138+
Use the following instructions if you installed Plone with Buildout.
139+
140+
### Install an add-on
141+
142+
Update the file {file}`buildout.cfg`.
143+
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
144+
145+
```cfg
146+
[buildout]
147+
extends =
148+
https://dist.plone.org/release/6-latest/versions.cfg
149+
150+
parts =
151+
instance
152+
153+
[instance]
154+
recipe = plone.recipe.zope2instance
155+
user = admin:admin
156+
http-address = 8080
157+
eggs =
158+
Plone
159+
collective.easyform
160+
161+
[versions]
162+
collective.easyform = 4.2.1
163+
```
164+
165+
```{tip}
166+
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
167+
```
168+
169+
To actually download and install the new add-on, run the following command.
170+
171+
```shell
172+
bin/buildout
173+
```
174+
175+
Then restart your instance.
176+
177+
```{seealso}
178+
{doc}`run-plone`
179+
```
180+
181+
182+
### Install an add-on from source
183+
184+
You can install an add-on from a source control system such as GitHub.
185+
186+
Update the file {file}`buildout.cfg`.
187+
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
188+
189+
```cfg
190+
[buildout]
191+
extends =
192+
https://dist.plone.org/release/6-latest/versions.cfg
193+
extensions = mr.developer
194+
auto-checkout =
195+
collective.easyform
196+
197+
parts =
198+
instance
199+
200+
[instance]
201+
recipe = plone.recipe.zope2instance
202+
user = admin:admin
203+
http-address = 8080
204+
eggs =
205+
Plone
206+
collective.easyform
207+
208+
[sources]
209+
collective.easyform = git https://github.com/collective/collective.easyform.git
210+
```
211+
212+
To actually download and install the new add-on, run the following command.
213+
214+
```shell
215+
bin/buildout
216+
```
217+
218+
Then restart your instance.
219+
220+
```{seealso}
221+
{doc}`run-plone`
222+
```
223+
224+
```{seealso}
225+
This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
226+
```

‎docs/admin-guide/configure-zope.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "Configure Zope options"
5+
"property=og:description": "Configure Zope options"
6+
"property=og:title": "Configure Zope"
7+
"keywords": "Plone 6, Zope, instance, app server, config, Cookieplone, Buildout, pip, cookiecutter-plone-starter, cookiecutter-zope-instance, plone.recipe.zope2instance"
8+
---
9+
10+
(configure-zope-label)=
11+
12+
# Configure Zope
13+
14+
Plone runs in an application server called {term}`Zope`.
15+
16+
You can configure your Zope instance's options, including the following.
17+
18+
- persistent storage: blobs, direct file storage, relational database, ZEO, and other storage mechanisms
19+
- ports
20+
- threads
21+
- cache
22+
- logging
23+
- debugging and profiling for development
24+
25+
26+
## Cookieplone
27+
28+
If you installed Plone using Cookieplone, `cookiecutter-plone-starter`, or pip, then Zope is configured using {term}`cookiecutter-zope-instance`.
29+
For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s README](https://github.com/plone/cookiecutter-zope-instance#readme).
30+
31+
32+
## Buildout
33+
34+
If you installed Plone using Buildout, then Zope is configured using `plone.recipe.zope2instance`.
35+
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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "How to install, operate, configure, and deploy Plone 6"
5+
"property=og:description": "How to install, operate, configure, and deploy Plone 6"
6+
"property=og:title": "Admin guide"
7+
"keywords": "Plone 6, admin, install, configuration, deploy"
8+
---
9+
10+
(admin-index-label)=
11+
12+
# Admin guide
13+
14+
In this part of the documentation, you can find how to install, operate, configure, and deploy Plone.
15+
16+
17+
```{toctree}
18+
:caption: Install
19+
:maxdepth: 1
20+
21+
/install/create-project-cookieplone
22+
install-buildout
23+
install-pip
24+
/install/create-project
25+
```
26+
27+
```{toctree}
28+
:caption: Operate
29+
:maxdepth: 1
30+
31+
run-plone
32+
configure-zope
33+
add-ons
34+
override-core
35+
/upgrade/index
36+
```
37+
% TODO: uncomment and add the following link to the Operate toctree when https://github.com/plone/volto/pull/6397 is merged.
38+
% https://volto--6397.org.readthedocs.build/development/add-ons/install-an-add-on.html
39+
% /volto/development/add-ons/index
40+
41+
42+
```{toctree}
43+
:maxdepth: 1
44+
:caption: Deploy
45+
46+
/install/containers/index
47+
```

0 commit comments

Comments
 (0)