You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Overhaul installation documentation, based on @mauritsvanrees's initial contribution.
This version provides context, structure, and order, leading the developer down the path to a successful installation experience according to their specific needs.
This is still a work in progress. Additional review is needed.
*[Community post](https://community.plone.org/t/our-pip-based-development-workflow-for-plone/14562) on work in progress with [`plone-kickstarter`](https://github.com/bluedynamics/plone-kickstarter) and [`mxdev`](https://github.com/bluedynamics/mxdev).
15
+
For trying out Plone 6, visit our official demonstration site located at:
To install Plone 6, you must satisfy system requirements and pre-requisites.
29
+
30
+
```{todo}
31
+
Add any missing requirements, including disk space.
32
+
```
33
+
34
+
- 2GB if using a container image, 4GB RAM if installing manually.
35
+
- Disk space (TBD).
36
+
- Either a UNIX-like operating system—such as Linux, Ubuntu, macOS—or Windows.
37
+
For Windows, it is a good idea to use [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/).
38
+
We strongly recommend using a recent version of your operating system released within the last 3 years.
39
+
Older systems might not be supported.
40
+
- Python 3.7, 3.8, or 3.9.
41
+
- Node.js 14 or 16.
42
+
- For Plone images, a container engine to develop, manage, and run OCI containers.
43
+
44
+
45
+
(install-index-choose-installation-method-label)=
46
+
47
+
## Choose an installation method
48
+
49
+
Developers may either [use the official Plone 6 images](install-index-image-installation-method-label) or [manually install Plone 6](install-index-manual-installation-method-label).
50
+
51
+
The Plone 6 images are compliant with the [Open Container Initiative (OCI)](https://opencontainers.org/).
52
+
They should work with any OCI-compliant container engine for developing, managing, and running Plone 6 images.
53
+
Two popular options include [podman](https://podman.io/) and [Docker](https://www.docker.com/products/docker-desktop/).
54
+
The Plone 6 images have all the system requirements, pre-requisites, and Plone 6 itself already installed, except those requirements needed for running the container engine itself.
55
+
This option is the quickest method to install and develop for Plone 6 and its packages.
56
+
57
+
There may be some cases where using a Plone 6 image is not practical or desired.
58
+
You might want to use an SQL database that is not PostgreSQL, or you might use a deployment workflow that has specific requirements.
59
+
For these situations, Plone 6 may be installed manually.
60
+
This method takes longer.
61
+
It might be a challenge if you bump up against system requirements, or need to resolve conflicts between required packages.
See their README files for installation and configuration instructions.
75
+
76
+
77
+
(install-index-manual-installation-method-label)=
78
+
79
+
## Manual installation method
80
+
81
+
As an overview, you will perform the following steps in order.
82
+
83
+
1. Install the Plone backend (which includes the Classic UI) with either [buildout](install-index-install-backend-label) or [pip](install-index-install-backend-pip-label).
84
+
1. Create the Plone Site in a web browser, choosing either the new Volto or the Classic UI for a frontend.
85
+
1. Install the Plone frontend (Volto) with node.
24
86
25
-
If you don't do Docker, you will have to do the backend by hand.
26
-
The links above should give you information on how to install the prerequisites, like Python, also on Windows.
27
-
Here, we will focus on Unix-like systems (Linux, Mac OSX), but Windows should work as well.
28
-
The steps are:
29
87
30
-
* Install the Plone (Classic) backend with buildout or pip.
31
-
* Create the Plone Site in the browser.
32
-
* Install the Plone frontend (Volto) with node.
88
+
(install-index-install-backend-label)=
33
89
34
-
Below we will install Plone 6.0.0a4.
35
-
You should use the latest from the Plone 6.0 series.
36
-
We install it with Python 3.9.
37
-
Python 3.7 and 3.8 are also supported.
38
-
Please use the most recent version supported by your platform.
90
+
### Install the Plone backend
39
91
92
+
You can install the Plone backend with either [buildout](install-index-install-backend-label) or [pip](install-index-install-backend-pip-label).
40
93
41
-
(installation-backend-buildout-label)=
42
94
43
-
## Install backend with buildout
95
+
(install-index-install-backend-buildout-label)=
44
96
45
-
Change to a new directory and put a file `buildout.cfg` in it:
97
+
#### Install backend with buildout
98
+
99
+
Create a new directory to hold your project, make it your current directory, and create a new file inside it called `buildout.cfg`.
100
+
This file will refer to the latest version of Plone, and the `user` value that will be used in the next step to create a Plone site.
101
+
Paste the following configuration information into it.
46
102
47
103
```ini
48
104
[buildout]
@@ -56,85 +112,142 @@ eggs =
56
112
user = admin:admin
57
113
```
58
114
59
-
Install it with:
115
+
Install Plone with the following shell commands.
60
116
61
117
```shell
118
+
# Create a Python virtual environment in the current directory
62
119
python3.9 -m venv .
120
+
# Install the latest Plone 6 requirements with pip
# Create a Plone 6 site with the given username and password in the current directory
80
143
bin/mkwsgiinstance -u admin:admin -d .
144
+
# Initialize Zope
81
145
bin/runwsgi -v etc/zope.ini
82
146
```
83
147
84
-
Note: you may need to edit `etc/zope.conf` to add a `blob-dir`.
148
+
```{warning}
149
+
You might need to edit `etc/zope.conf` to add a `blobstorage` node with a `blob-dir` entry.
85
150
See [issue 3345](https://github.com/plone/Products.CMFPlone/issues/3345#issuecomment-953700024).
151
+
```
152
+
86
153
154
+
(install-index-create-plone-site-label)=
87
155
88
-
(installation-create-plone-backend-label)=
156
+
## Create a Plone site
89
157
90
-
## Create Plone backend
158
+
After you have installed the backend with buildout or pip, open a browser and visit http://localhost:8080/.
91
159
92
-
After you have installed the backend with buildout or pip, open a browser and go to http://localhost:8080/.
93
-
Click 'Create a new Plone site' to prepare for the new Volto frontend.
94
-
If you want Plone Classic instead, click 'Create Classic Plone site'.
95
-
(If this button is not available, then you did not install `plone.volto` with buildout or pip. 'Create a new Plone site' will create a Classic site then.)
160
+
Choose either Volto or Classic UI for the frontend.
96
161
97
-
Note: For Volto, make sure the Path identifier is Plone. You can change this, but then you need to change some Volto frontend configuration as well.
162
+
- For a new Volto frontend, click {guilabel}`Create a new Plone site`to prepare a Plone site and its backend.
98
163
164
+
```{note}
165
+
If this button is not available, then you did not install `plone.volto` with buildout or pip.
166
+
```
167
+
168
+
```{attention}
169
+
For Volto, make sure the `Path` identifier is `Plone`.
170
+
You can change this, but then you need to change some Volto frontend configuration as well.
171
+
```
172
+
173
+
- For a Plone Classic UI frontend, click {guilabel}`Create Classic Plone site`.
174
+
99
175
Submit the form and your backend is ready.
100
-
If you want Classic Plone, you are done.
101
-
If you want the full Plone 6 with Volto, read on.
102
176
177
+
If you created a Plone site with a Classic UI frontend, then you have completed installation.
178
+
179
+
If a created a Plone site with a Volto frontend, continue with the next steps.
180
+
181
+
182
+
(install-index-volto-frontend-node-label)=
183
+
184
+
## Volto frontend with node
185
+
186
+
We recommend that you read the chapter {ref}`frontend-getting-started-installing-volto-label` for details.
187
+
188
+
189
+
(install-index-nvm-node-version-manager-label)=
103
190
104
-
(installation-frontend-node-label)=
191
+
### `nvm`, the Node Version Manager
105
192
106
-
## Frontend with node
193
+
We recommend that you install [`nvm`, or Node Version Manager](https://github.com/nvm-sh/nvm).
194
+
This makes it possible to switch to any version of [`node` (Node.JS)](https://nodejs.org/en/) and [`npm` (Node Package Manager)](https://www.npmjs.com/) for any project on which you might work.
107
195
108
-
You should probably read the chapter on {ref}`frontend-getting-started-installing-volto-label`.
109
-
But the following gives you the general idea.
196
+
- On Linux: `apt-get install nvm`
197
+
- On Mac: `brew install nvm`
198
+
- Or use the installation procedure detailed in the [nvm documentation](https://github.com/nvm-sh/nvm)
110
199
111
-
First you may want to install `nvm`, the Node Version Manager:
200
+
With `nvm` installed, you can use it to install and use a supported version of `node` and `npm` using the following shell commands.
201
+
202
+
```shell
203
+
nvm install 16
204
+
nvm use 16
205
+
```
112
206
113
-
* On Linux: `apt-get install nvm`
114
-
* On Mac: `brew install nvm`
115
-
* Or use the installation procedure detailed in the [nvm documentation](https://github.com/nvm-sh/nvm)
116
207
117
-
You use `nvm` to install recent `node/npm/yarn` versions:
208
+
(install-index-install-yarn-label)=
209
+
210
+
## Install Yarn
211
+
212
+
Volto requires [Yarn Classic](https://classic.yarnpkg.com/lang/en/), a dependency manager for JavaScript code.
213
+
Install Yarn with the following command.
118
214
119
215
```shell
120
-
nvm install --lts
121
216
npm install --global yarn
122
217
```
123
218
124
-
Create a Volto project:
219
+
220
+
(install-index-create-volto-project-label)=
221
+
222
+
### Create a Volto project
223
+
224
+
Create a Volto project using the following shell command.
125
225
126
226
```shell
127
227
npm init yo @plone/volto
128
228
```
129
229
130
-
This will take long, and then ask for a project name.
230
+
This will take some time ☕️.
231
+
Toward the end of the process, it will ask you for a project name.
232
+
Enter the name of your project, using only lowercase letters.
131
233
It will create a directory with this name.
132
-
Go to that directory and start the frontend:
234
+
Go to that directory and start the frontend with the following command.
133
235
134
236
```shell
135
237
yarn start
136
238
```
137
239
138
-
In your browser go to [http://localhost:3000](http://localhost:3000/).
240
+
In your browser, visit [http://localhost:3000](http://localhost:3000/).
241
+
242
+
Congratulations!
243
+
You have completed the installation of Plone 6 with Volto for its frontend.
244
+
Welcome to Plone 6!
245
+
246
+
247
+
(install-index-create-volto-project-label)=
248
+
249
+
## Additional references
139
250
140
-
You are done. Welcome to Plone 6!
251
+
-[Installation instructions from the Mastering Plone 6 training](https://training.plone.org/5/mastering-plone/installation.html)
-[Community post](https://community.plone.org/t/our-pip-based-development-workflow-for-plone/14562) on work in progress with [`plone-kickstarter`](https://github.com/bluedynamics/plone-kickstarter) and [`mxdev`](https://github.com/bluedynamics/mxdev).
0 commit comments