Skip to content

Commit 5a5fb14

Browse files
davisaglistevepiercy
davisagli
and
stevepiercy
authored
Add "create project" docs for cookieplone (#1714)
* Add "create project" docs for cookieplone * Add overlooked comma * Rename file * Rename file * Remove "the" from Classic UI. MyST syntax standard. Clarify introduction * Apply suggestions from code review * Overhaul the Install index. - promote stable releases over development pre-releases - Move demos to end - Replace Sphinx Design grid and cards a plain old definition list. * Simplify introductions for create-project* * Update meta information * Current version of Sphinx does not support replacements in includes, so use this temporary workaround and add TODO. * Hyphenate pre-requisite and tidy * Update meta information * Use narrow terminal to avoid horizontal scrolling of console. * Add next steps to view the site. Much excite! * Update meta information and correct Volto version * Correct introduction * Add terms Cookieplone and cookieplone-templates to Glossary. * Use include for Python prerequisite * Update docs/glossary.md Remove documentation as a Cookieplone option Co-authored-by: David Glick <[email protected]> * Update docs/install/create-project-cookieplone.md Co-authored-by: David Glick <[email protected]> * Include corepack enable as an enumerated step, and use shell for syntax * Avoid horizontal scrolling and anonymize path to project * Finalize tidy and update screenshots to 2024 * Link to correct repo. See plone/cookieplone#41 * Add plone/generator-volto deprecation to Glossary * Cannot use `@` at the start of a term in the Glossary * Nope, `@` is fine, there was whitespace that broke the glossary. * Add note about installing Pillow requirements. See #1712 * Update docs/glossary.md Co-authored-by: David Glick <[email protected]> --------- Co-authored-by: Steve Piercy <[email protected]>
1 parent a39a990 commit 5a5fb14

12 files changed

+656
-85
lines changed

‎docs/_inc/_hardware-requirements.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
The hardware requirements below give a rough estimate of the minimum hardware setup needed for a Plone server.
2+
3+
A single Plone installation is able to run many Plone sites.
4+
5+
- Installation of the Plone backend and Classic UI frontend requires a minimum of 256 MB of RAM and 2GB of disk swap space.
6+
- Installation of the Volto frontend requires a minimum of 2GB of RAM.
7+
- After installation, running Plone requires a minimum of 256 MB RAM and 512 MB of disk swap space per Plone site.
8+
2 GB or more RAM per Plone site is recommended.
9+
- Minimum 512 MB hard disk space is required.
10+
40 GB or more hard disk space is recommended.
11+
12+
13+
````{warning}
14+
{term}`Add-on` products and caching solutions may also increase RAM and disk swap space requirements.
15+
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).
16+
```{seealso}
17+
[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).
18+
```
19+
````

‎docs/_inc/_install-pillow.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
``````{note}
2+
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.
3+
4+
`````{tab-set}
5+
6+
````{tab-item} macOS
7+
```shell
8+
brew install zlib libjpeg
9+
```
10+
````
11+
12+
````{tab-item} Linux
13+
```shell
14+
apt-get zlib libjpeg
15+
```
16+
````
17+
`````
18+
19+
You will then need to run `make install` again.
20+
21+
```{seealso}
22+
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.
23+
```
24+
``````

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

‎docs/_static/plone-classic-ui-landing-page.png

54.5 KB
Loading

‎docs/_static/plone-classic-ui-site-page.png

89.5 KB
Loading

‎docs/_static/plone-home-page.png

79.2 KB
Loading

‎docs/_static/plone-login-page.png

-342 Bytes
Loading

‎docs/glossary.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,25 @@ Cookiecutter
2828
A command-line utility that creates projects from cookiecutters (project templates), for example, creating a Python package project from a Python package project template.
2929
[See Cookiecutter's documentation](https://cookiecutter.readthedocs.io/en/stable/).
3030
31+
Cookieplone
32+
```{versionadded} Volto 18.0.0-alpha.43
33+
```
34+
35+
[Cookieplone](https://github.com/plone/cookieplone) is the method to create a Plone project.
36+
You can use Cookieplone to build a backend add-on, a new Volto add-on, or a full project with both backend and frontend.
37+
Cookieplone simplifies the process using robust Cookiecutter templates from {term}`cookieplone-templates`.
38+
39+
cookieplone-templates
40+
[`cookieplone-templates`](https://github.com/plone/cookieplone-templates) is a collection of templates used by {term}`Cookieplone`.
41+
42+
@plone/generator-volto
43+
plone/generator-volto
44+
```{deprecated} Volto 18.0.0-alpha.43
45+
```
46+
47+
[@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.
48+
See {ref}`upgrade-18-cookieplone-label`.
49+
3150
cookiecutter-plone-starter
3251
[cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter/) is a framework for jumpstarting Plone 6 projects quickly.
3352

‎docs/install/create-project-classic-ui.md

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "Create a Plone project with Classic UI (stable release)"
5+
"property=og:description": "Create a Plone project with Classic UI (stable release)"
6+
"property=og:title": "Create a Plone project with Classic UI (stable release)"
7+
"keywords": "Plone, Plone 6, Classic UI, create, project, install, cookiecutter, Cookieplone"
8+
---
9+
10+
11+
(create-a-project-classic-ui-label)=
12+
13+
# Create a project with Classic UI (stable release)
14+
15+
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.
16+
17+
```{seealso}
18+
For other installation options, see {doc}`/install/index`.
19+
```
20+
21+
22+
## System requirements
23+
24+
Plone 6 has both hardware requirements and software pre-requisites.
25+
26+
27+
### Hardware requirements
28+
29+
```{include} /_inc/_hardware-requirements.md
30+
```
31+
32+
### Pre-requisites for installation
33+
34+
```{include} ../volto/contributing/install-operating-system.md
35+
```
36+
37+
- Python {SUPPORTED_PYTHON_VERSIONS}
38+
- {term}`pipx`
39+
- {term}`GNU make`
40+
- {term}`Git`
41+
42+
43+
#### Python
44+
45+
```{include} /_inc/_install-python.md
46+
```
47+
48+
49+
#### pipx
50+
51+
Install {term}`pipx`.
52+
53+
```shell
54+
pip install pipx
55+
```
56+
57+
58+
#### Make
59+
60+
```{include} ../volto/contributing/install-make.md
61+
```
62+
63+
64+
#### Git
65+
66+
```{include} ../volto/contributing/install-git.md
67+
```
68+
69+
70+
## Generate the project
71+
72+
After satisfying the pre-requisites, generate the project.
73+
74+
```shell
75+
pipx run cookieplone backend_addon
76+
```
77+
78+
You will be presented with a series of prompts.
79+
You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values.
80+
For ease of documentation, we will use the default values.
81+
82+
```{tip}
83+
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).
84+
```
85+
86+
```{important}
87+
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).
88+
Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the same package.
89+
```
90+
91+
```console
92+
% pipx run cookieplone backend_addon
93+
╭─────────────────────────────────── cookieplone ────────────────────────────────────╮
94+
│ │
95+
│ .xxxxxxxxxxxxxx. │
96+
│ ;xxxxxxxxxxxxxxxxxxxxxx; │
97+
│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx; │
98+
│ xxxxxxxxxx xxxxxxxxxx │
99+
│ xxxxxxxx. .xxxxxxxx │
100+
│ xxxxxxx xxxxxxx: xxxxxxx │
101+
│ :xxxxxx xxxxxxxxxx xxxxxx: │
102+
│ :xxxxx+ xxxxxxxxxxx +xxxxx: │
103+
│ .xxxxx. :xxxxxxxxxx .xxxxx. │
104+
│ xxxxx+ ;xxxxxxxx +xxxxx │
105+
│ xxxxx +xx. xxxxx. │
106+
│ xxxxx: .xxxxxxxx :xxxxx │
107+
│ xxxxx .xxxxxxxxxx xxxxx │
108+
│ xxxxx xxxxxxxxxxx xxxxx │
109+
│ xxxxx .xxxxxxxxxx xxxxx │
110+
│ xxxxx: .xxxxxxxx :xxxxx │
111+
│ .xxxxx ;xx. ... xxxxx. │
112+
│ xxxxx+ :xxxxxxxx +xxxxx │
113+
│ .xxxxx. :xxxxxxxxxx .xxxxx. │
114+
│ :xxxxx+ xxxxxxxxxxx ;xxxxx: │
115+
│ :xxxxxx xxxxxxxxxx xxxxxx: │
116+
│ xxxxxxx xxxxxxx; xxxxxxx │
117+
│ xxxxxxxx. .xxxxxxxx │
118+
│ xxxxxxxxxx xxxxxxxxxx │
119+
│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+ │
120+
│ ;xxxxxxxxxxxxxxxxxxxxxx; │
121+
│ .xxxxxxxxxxxxxx. │
122+
│ │
123+
╰────────────────────────────────────────────────────────────────────────────────────╯
124+
╭─────────────────────────────────── Plone Addon ────────────────────────────────────╮
125+
│ Creating a new Plone Addon │
126+
╰────────────────────────────────────────────────────────────────────────────────────╯
127+
[1/7] Addon Title (Addon):
128+
[2/7] A short description of your addon (A new addon for Plone):
129+
[3/7] Author (Plone Community):
130+
[4/7] Author E-mail ([email protected]):
131+
[5/7] GitHub Username or Organization (collective):
132+
[6/7] Python package name (collective.addon):
133+
[7/7] Support headless Plone?
134+
1 - Yes
135+
2 - No
136+
Choose from [1/2] (1):
137+
-> Initialize Git repository
138+
╭───────────────────────────── New addon was generated ──────────────────────────────╮
139+
│ │
140+
│ Addon │
141+
│ │
142+
│ Now, enter the repository run the code formatter with: │
143+
│ │
144+
│ make format │
145+
│ │
146+
│ start coding, and push to your organization. │
147+
│ │
148+
│ Sorry for the convenience, │
149+
│ The Plone Community. │
150+
│ │
151+
│ https://plone.org/ │
152+
╰────────────────────────────────────────────────────────────────────────────────────╯
153+
```
154+
155+
156+
## Install the project
157+
158+
Change to your project directory.
159+
160+
```shell
161+
cd collective.addon
162+
```
163+
164+
To install the project's dependencies, use the following command.
165+
166+
```shell
167+
make install
168+
```
169+
170+
This will take a few minutes.
171+
☕️
172+
173+
When the process completes successfully, it will exit with no message.
174+
175+
```{include} /_inc/_install-pillow.md
176+
```
177+
178+
179+
## Start Plone
180+
181+
To start Plone, issue the following command.
182+
183+
```shell
184+
make start
185+
```
186+
187+
The Plone backend server starts up and emits messages to the console.
188+
189+
```console
190+
2024-09-25 16:47:15,699 INFO [chameleon.config:39][MainThread] directory cache: /<path-to-project>/instance/var/cache.
191+
2024-09-25 16:47:16,387 WARNING [ZODB.FileStorage:412][MainThread] Ignoring index for /<path-to-project>/instance/var/filestorage/Data.fs
192+
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.
193+
2024-09-25 16:47:17,018 INFO [plone.volto:23][MainThread] Aliasing collective.folderish classes to plone.volto classes.
194+
2024-09-25 16:47:17,760 INFO [Zope:42][MainThread] Ready to handle requests
195+
Starting server in PID 20912.
196+
2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://[::1]:8080
197+
2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080
198+
```
199+
200+
You can stop the site with {kbd}`ctrl-c`.
201+
202+
203+
## Create Classic UI Plone site
204+
205+
While the Plone backend server is running, open a browser and visit the following URL.
206+
207+
http://localhost:8080
208+
209+
```{image} /_static/plone-classic-ui-landing-page.png
210+
:class: figure
211+
:alt: Plone Classic UI landing page
212+
```
213+
214+
Click the button {guilabel}`Create Classic UI Plone site` to do exactly that.
215+
216+
Use the username and password of `admin` to authenticate.
217+
You will be redirected to the Create a Plone site page.
218+
219+
```{image} /_static/plone-classic-ui-site-page.png
220+
:class: figure
221+
:alt: Plone Classic UI site page
222+
```
223+
224+
Enter values for {guilabel}`Path identifier`, {guilabel}`Title`, {guilabel}`Language`, and {guilabel}`Default timezone`.
225+
The default values are usually good.
226+
227+
Click the button {guilabel}`Create Plone site`.
228+
229+
You will be redirected to the Plone site you just created.

0 commit comments

Comments
 (0)