Skip to content

Commit 267a2e4

Browse files
davisaglidavisagli
committed
update installation for new monorepo project
1 parent cef40f2 commit 267a2e4

2 files changed

Lines changed: 72 additions & 93 deletions

File tree

‎docs/mastering-plone/_static/instructions_plone_running.png‎

-301 Bytes
Loading

‎docs/mastering-plone/installation.md‎

Lines changed: 72 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -13,106 +13,118 @@ This chapter provides instructions on how to install **Plone with the training c
1313

1414
For general Plone installation, deployment, and hosting instructions, refer to the authoritative Plone 6 documentation in {doc}`plone6docs:install/index`.
1515

16-
(installation-tools-label)=
16+
We encourage you to install and run `Plone` on your own machine, as you will have important benefits:
17+
18+
- You can work with your favorite editor.
19+
- You have all the code of Plone at your fingertips in `site-packages` or `node_modules`.
1720

18-
## Technologies and Tools
1921

20-
- [Linux (Ubuntu)](https://ubuntu.com/)
21-
- [Python](https://www.python.org)
22-
- [React](https://react.dev/)
22+
(installation-prerequisites-label)=
23+
24+
## Prerequisites
2325

2426
We recommend to work on Linux or Mac, not Windows.
2527

28+
You will need some other software in order to install and run Plone.
29+
Follow {ref}`create-project-cookieplone-prerequisites-for-installation-label` to install the following tools, if you don't have them already:
30+
31+
- uv
32+
- nvm
33+
- Node.js
34+
- GNU make
35+
- Git
36+
2637

27-
(installation-label)=
38+
(installation-project-structure)=
2839

29-
## Set up
40+
## The project structure
3041

31-
We install the `Plone` backend and its `React`-based frontend `Volto`, starting with the following folder structure:
42+
The main project for this training is structured as a {term}`monorepo`.
43+
It is a single Git repository which includes both the Plone backend and its React-based frontend Volto, in the following folder structure:
3244

3345
```text
34-
training
46+
mastering-plone-project
3547
├── backend
3648
└── frontend
3749
```
3850

39-
In {file}`backend` we install Plone and add our custom Python code.
40-
In {file}`frontend` we install Volto and add our custom React code.
51+
The {file}`backend` folder contains Plone and our custom backend code and configuration.
52+
The {file}`frontend` folder contains Volto and our custom frontend code and configuration.
4153

4254

43-
(installation-install-backend-label)=
44-
45-
## Installing the backend
46-
47-
We encourage you to install and run `Plone` on your own machine, as you will have important benefits:
48-
49-
- You can work with your favorite editor.
50-
- You have all the code of Plone at your fingertips in `site-packages` tree.
55+
(installation-project-label)=
5156

57+
## Install the project
5258

53-
### Prerequisites
54-
55-
- `make`. We recommend upgrading to at least `make` 4.
56-
57-
58-
### Installation
59-
60-
Set up the [backend with the training code](https://github.com/collective/training_buildout): add-ons `ploneconf.site` and `training.votable`.
59+
Clone the [`mastering-plone-project` repository](https://github.com/collective/mastering-plone-project).
6160

6261
```shell
63-
mkdir training
64-
cd training
65-
git clone https://github.com/collective/training_buildout.git backend
66-
cd backend
62+
git clone git@github.com:collective/mastering-plone-project.git
63+
cd mastering-plone-project
64+
```
65+
66+
```{tip}
67+
The initial structure for this project repository was created by following {ref}`create-project-cookieplone-create-volto-project-label`.
6768
```
6869

69-
Build your backend with:
70+
Install the project with:
7071

7172
```shell
72-
make build
73+
make install
7374
```
7475

75-
This build executes multiple tasks.
76-
The build
77-
- creates a Python virtual environment and installs prerequisites
78-
- generates a file structure to be prepared to install Plone packages with pip
79-
- generates Zope configuration with Cookiecutter
76+
The install command executes multiple tasks.
77+
It will:
78+
- create a Python virtual environment and install Python dependencies using uv
79+
- generate configuration for a Zope instance using `cookiecutter-zope-instance`
80+
- install Node dependencies using pnpm
81+
- create a new Plone site with our `ploneconf.site` add-on installed
8082

81-
By creating and working with a **Python virtual environment**, we are independent of the system Python installation. We install packages and its version according to our needs.
83+
By creating and working with a **Python virtual environment**, we are independent of the system Python installation.
84+
The correct version of Python and dependency packages are installed in an isolated path (`backend/.venv`).
8285

83-
The build generates a file structure to be prepared to install **Plone from packages** with `pip` and `mxdev`. The tool `mxdev` helps with configuration files to define which add-ons and which versions to install.
84-
It also allows to override Plone core package versions or force a checkout from `github`.
85-
The documentation {doc}`plone6docs:admin-guide/add-ons` provides information on common tasks.
86+
The specification of which Python packages to install comes from {file}`backend/pyproject.toml`.
8687

8788
The build generates **Zope configuration** files with Cookiecutter `cookiecutter-zope-instance`.
88-
The file we will modify to update our Zope / Plone configuration is `instance.yaml`.
89+
The file we will modify to update our Zope / Plone configuration is {file}`backend/instance.yaml`.
8990
In this file we will add add-ons that are installed as Python packages and shall be loaded in our instance.
9091
`instance.yaml` is the one configuration file for our Zope / Plone instance.
9192
The documentation of [`cookiecutter-zope-instance`](https://github.com/plone/cookiecutter-zope-instance) explains a lot more that can be configured like the port or another storage.
9293

93-
After changes in configuration files, a re-build is necessary:
94+
The specification of which Node.js packages to install comes from {file}`frontend/package.json` and {file}`frontend/mrs.developer.json`.
95+
96+
After changes in configuration files, a reinstall is necessary:
9497

9598
```shell
96-
make build
99+
make install
97100
```
98101

102+
(installation-start-backend-label)=
103+
104+
## Start the backend
105+
99106
We are now ready to start the backend with:
100107

101108
```shell
102-
make start
109+
make backend-start
103110
```
104111

105112
Voilà, your Plone is up and running on http://localhost:8080.
106113

107114
The output should be similar to:
108115

109116
```shell
110-
katjasuss@purpur training % make start
111-
112-
2022-09-27 08:57:23,961 INFO [Zope:42][MainThread] Ready to handle requests
113-
Starting server in PID 28745.
114-
2022-09-27 08:57:23,963 INFO [waitress:486][MainThread] Serving on http://[::1]:8080
115-
2022-09-27 08:57:23,963 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080
117+
% make backend-start
118+
119+
2026-07-21 15:12:15,604 INFO [chameleon.config:40][MainThread] directory cache: /Users/davisagli/Plone/mastering-plone-project/backend/instance/var/cache.
120+
2026-07-21 15:12:16,003 WARNING [ZODB.FileStorage:409][MainThread] Ignoring index for /Users/davisagli/Plone/mastering-plone-project/backend/instance/var/filestorage/Data.fs
121+
2026-07-21 15:12:16,155 INFO [plone.restapi.patches:15][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB.
122+
2026-07-21 15:12:16,364 INFO [plone.app.event:17][MainThread] icalendar has been set up to use pytz instead of zoneinfo.
123+
2026-07-21 15:12:17,232 INFO [plone.volto:22][MainThread] Aliasing collective.folderish classes to plone.volto classes.
124+
2026-07-21 15:12:17,630 INFO [Zope:42][MainThread] Ready to handle requests
125+
Starting server in PID 87938.
126+
2026-07-21 15:12:17,633 INFO [waitress:449][MainThread] Serving on http://127.0.0.1:8080
127+
2026-07-21 15:12:17,633 INFO [waitress:449][MainThread] Serving on http://[::1]:8080
116128
```
117129

118130
Troubleshooting: We are here to help: Please file an issue in [training repository](https://github.com/plone/training/issues).
@@ -123,58 +135,25 @@ Point your browser to <http://localhost:8080> to see `Plone` running.
123135
:alt: Plone is running.
124136
:scale: 50 %
125137
126-
`Plone`, up and running.
138+
Plone, up and running.
127139
```
128140

129-
There is no Plone site yet.
130-
We will create one in the next chapter.
141+
You can see that there is already an existing Plone site that was created by the install command.
131142

132143
You can stop the running instance anytime using {kbd}`ctrl c`.
133144

134145

135-
(installation-install-frontend-label)=
136-
137-
## Installing the frontend
138-
139-
You have two options:
140-
141-
> 1. Create the frontend from scratch using {term}`Cookieplone`.
142-
> 2. Use the prepared Volto project [volto-ploneconf](https://github.com/collective/volto-ploneconf) with all the code for the training.
143-
144-
145-
### Option 1: Frontend from scratch
146-
147-
148-
Follow the instructions of `docs.plone.org`: {doc}`plone6docs:volto/development/creating-project`.
149-
146+
(installation-start-frontend-label)=
150147

151-
### Option 2. Start with prepared training project `volto-ploneconf` with all code for the training
152-
153-
Prepare the prerequisites explained in {ref}`plone6docs:create-project-cookieplone-prerequisites-for-installation-label`.
154-
Be aware that Volto 18 recommends `pnpm` instead of `yarn` as package manager and project manager.
155-
156-
Get the code for the frontend from GitHub and install:
157-
158-
```shell
159-
cd training
160-
git clone https://github.com/collective/volto-ploneconf.git frontend
161-
cd frontend
162-
make install
163-
```
164-
165-
Now you can start the app with:
166-
167-
```shell
168-
make start
169-
```
148+
## Start the frontend
170149

171-
which is a
150+
The frontend must be run as a separate process.
151+
Open a second terminal and start it with:
172152

173153
```shell
174-
pnpm start
154+
make frontend-start
175155
```
176156

177-
Point your browser to <http://localhost:3000> and see that the app is up and running, albeit without content.
178-
We will create a Plone instance in the next chapter.
157+
Point your browser to <http://localhost:3000> and see that the app is up and running.
179158

180159
You can stop the frontend anytime using {kbd}`ctrl c`.

0 commit comments

Comments
 (0)