Install Plone with cookiecutter-plone-starter
(deprecated)#
Deprecated since version Plone: 6.1 and Volto 18
This method to install Plone is now deprecated. It was the recommended way to start a new Plone project with Plone 6.0 and Volto 17 or earlier. For other installation options, see Install Plone.
This chapter describes how you can create a web application using the cookiecutter-plone-starter template.
This template creates a web application using Plone with the Volto frontend, along with tools for development and deployment.
System requirements#
Plone 6.0 has both hardware requirements and software prerequisites.
Supported web browsers#
You can view the list of supported browsers for Volto at Browserslist.
These browsers are set according to the browserslist
key in Volto's package.json
file, whose content is below.
>1%
last 4 versions
Firefox ESR
not dead
You can view the list of supported browsers for Classic UI at Browserslist.
The supported web browsers for Classic UI are set according to Bootstrap. The following code snippet is the browserslist configuration for Bootstrap 5.3.3.
>= 0.5%
last 2 major versions
not dead
Chrome >= 60
Firefox >= 60
Firefox ESR
iOS >= 12
Safari >= 12
not Explorer <= 11
Hardware requirements#
The hardware requirements below give a rough estimate of the minimum hardware setup needed for a Plone server.
A single Plone installation is able to run many Plone sites.
Installation of the Plone backend and Classic UI frontend requires a minimum of 256 MB of RAM and 2GB of disk swap space.
Installation of the Volto frontend requires a minimum of 2GB of RAM.
After installation, running Plone requires a minimum of 256 MB RAM and 512 MB of disk swap space per Plone site. 2 GB or more RAM per Plone site is recommended.
Minimum 512 MB hard disk space is required. 40 GB or more hard disk space is recommended.
Warning
Add-on products and caching solutions may also increase RAM and disk swap space requirements. 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 or GitHub Actions.
Prerequisites for installation#
An operating system that runs all the requirements mentioned. Most UNIX-based operating systems are supported, including many Linux distributions, macOS, or Windows Subsystem for Linux (WSL) on Windows. A UNIX-based operating system is recommended.
Important
Windows alone is not recommended because it does not support GNU make. If you get Plone to run on Windows alone, please feel free to document and share your process.
Python#
Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, pyenv, that allows you to install multiple versions of Python on your development environment without destroying your system's Python.
Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.
Warning
Do not create or activate a Python virtual environment at this time. The instructions below will create one.
pipx#
Install pipx for your active Python, and ensure it is on your $PATH
.
Carefully read the console output for further instructions, and follow them, if needed.
python3 -m pip install pipx
pipx ensurepath
nvm#
The following terminal session commands use bash
for the shell.
Adapt them for your flavor of shell.
See also
See the nvm
install and update script documentation.
For the fish
shell, see nvm.fish
.
Create your shell profile, if it does not exist.
touch ~/.bash_profile
Download and run the
nvm
install and update script, and pipe it intobash
.curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.39.5/install.sh | bash
Source your profile. Alternatively close the session and open a new one.
source ~/.bash_profile
Verify that the
nvm
version is that which you just installed or updated:nvm --version
Node.js#
Install or update the supported LTS versions of Node.js, then activate the version supported in Volto.
nvm install --lts nvm use --lts
Verify that the supported version of Node.js is activated.
node -v
Yeoman and the Volto boilerplate generator#
Install Yeoman and the Volto boilerplate generator.
npm install -g yo @plone/generator-volto
Yarn#
Use Corepack to enable Yarn, which was already installed with the supported version of Node.js.
Open a terminal and type:
corepack enable
Important
The preceding instructions will not work if you have used another package manager, such as Homebrew on macOS, to install Yarn. You can verify where you installed Yarn.
which yarn
# /opt/homebrew/bin/yarn
If the console includes homebrew
in the path, then you must uninstall it.
brew uninstall yarn
Now the instructions to install Yarn should work.
Make#
Make comes installed on most Linux distributions.
On macOS, you must first install Xcode, then install its command line tools.
On Windows, it is strongly recommended to Install Linux on Windows with WSL, which will include make
.
Finally, it is a good idea to update your system's version of make
, because some distributions, especially macOS, have an outdated version.
Use your favorite search engine or trusted online resource for how to update make
.
Docker#
Install Docker Desktop for your operating system. Docker Desktop includes all Docker tools.
Note
For some Linux distributions, you might need to create a group docker
and add your user to this group.
See Linux post-installation steps for Docker Engine for details.
Git#
Install git for your operating system.
Install Plone 6.0#
We install Plone 6.0 with pipx, Cookiecutter, mxdev, make, and other developer tools.
Create a new directory to hold your project, and make it your current directory.
mkdir my_project
cd my_project
Issue the following command to install or update cookiecutter
, then run it to create a Plone project skeleton using the Cookiecutter cookiecutter-plone-starter.
pipx run cookiecutter gh:collective/cookiecutter-plone-starter
You will be presented with a series of prompts.
You can accept the default values in square brackets ([default-option]
) by hitting the Enter key, or enter your preferred values.
For ease of documentation, we will use the default values.
Tip
See the cookiecutter's README for how to Use options to avoid prompts.
Important
For Project Slug, you must not use any of the Plone core package names listed in constraints.txt
.
Note that pip normalizes these names, so plone.volto
and plone-volto
are the same package.
% pipx run cookiecutter gh:collective/cookiecutter-plone-starter
Cookiecutter Plone Starter
================================================================================
Sanity checks
--------------------------------------------------------------------------------
[1/5] Python: ✓
[2/5] Node: ✓
[3/5] yo: ✓
[4/5] Docker: ✓
[5/5] git: ✓
Project details
--------------------------------------------------------------------------------
[1/19] Project Title (Project Title): Plone Conference Website 2070
[2/19] Project Description (A new project using Plone 6.):
[3/19] Project Slug (Used for repository id) (plone-conference-website-2070):
[4/19] Project URL (without protocol) (plone-conference-website-2070.example.com):
[5/19] Author (Plone Foundation): Elli
[6/19] Author E-mail (collective@plone.org): elli@plone.org
[7/19] Python Package Name (plone_conference_website_2070):
[8/19] Volto Addon Name (volto-plone-conference-website-2070):
[9/19] Choose a Python Test Framework
1 - pytest
2 - unittest
Choose from [1/2] (1):
[10/19] Plone Version (6.0.8):
[11/19] Should we use Volto Alpha Versions? (No): yes
[12/19] Volto Version (18.0.0-alpha.1):
[13/19] Volto Generator Version (8.0.0):
[14/19] Language
1 - English
2 - Deutsch
3 - Español
4 - Português (Brasil)
5 - Nederlands
6 - Suomi
Choose from [1/2/3/4/5/6] (1):
[15/19] GitHub Username or Organization (collective): ellizurigo
[16/19] Container Registry
1 - GitHub Container Registry
2 - Docker Hub
Choose from [1/2] (1):
[17/19] Should we setup a caching server?
1 - Yes
2 - No
Choose from [1/2] (1): 2
[18/19] Add Ansible playbooks?
1 - Yes
2 - No
Choose from [1/2] (1):
[19/19] Add GitHub Action to Deploy this project?
1 - Yes
2 - No
Choose from [1/2] (1):
Plone Conference Website 2070 generation
--------------------------------------------------------------------------------
Summary:
- Plone version: 6.0.8
- Volto version: 18.0.0-alpha.1
- Volto Generator version: 8.0.0
- Output folder: /Users/katjasuss/Desktop/_temp/scratch_cookiecutter_plone/plone-conference-website-2070
Frontend codebase:
- Installing required npm packages
- Generate frontend application with @plone/volto 18.0.0-alpha.1
Backend codebase
- Remove folder src/plone_conference_website_2070/src/plone_conference_website_2070/tests not used by pytest
- Format generated code in the backend
================================================================================
Project "Plone Conference Website 2070" was generated
--------------------------------------------------------------------------------
Now, code it, create a git repository, push to your organization.
Sorry for the convenience,
The Plone Community.
================================================================================
Change to your project directory plone-conference-website-2070
.
cd plone-conference-website-2070
Next you switch to using make
.
To see all available commands and their descriptions, enter the following command.
make help
To install both the Plone backend and frontend, use the following command.
make install
This will take a few minutes. ☕️ First the backend, then the frontend will be installed.
When the process completes successfully, it will exit with no message.
Note
After generating a project, then running make install
, if you see an error message ERROR: Failed building wheel for Pillow
or The headers or library files could not be found for jpeg, a required dependency when compiling Pillow from source.
, then you need to install Pillow's dependencies.
brew install zlib libjpeg
apt install zlib1g-dev libjpeg8-dev
You will then need to run make install
again.
See also
See also the Pillow documentation External Libraries for additional libraries that you might need.
Note
If you used a Plone core package name, then make install
will return an error message such as the following.
ERROR: Cannot install plone-volto 1.0.0a1 (from /home/username/projects/volto/plone-volto/backend/src/plone_volto) because these package versions have conflicting dependencies.
The conflict is caused by:
The user requested plone-volto 1.0.0a1 (from /home/username/projects/volto/plone-volto/backend/src/plone_volto)
The user requested (constraint) plone-volto==4.2.0
To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict
ERROR: ResolutionImpossible: for help visit
make[2]: *** [Makefile:112: build-dev] Error 1
make[2]: Leaving directory '/home/username/projects/volto/plone-volto/backend'
make[1]: *** [Makefile:46: install-backend] Error 2
make[1]: Leaving directory '/home/username/projects/volto/plone-volto'
You must delete your project, follow the important note, and run the cookiecutter again.
Start Plone#
Plone 6 has two servers: one for the frontend, and one for the backend. As such, we need to maintain two active shell sessions, one for each server, to start your Plone site.
Start Plone backend#
In the currently open session, issue the following command.
make start-backend
The Plone backend server starts up and emits messages to the console.
2022-09-24 01:30:17,799 WARNING [ZODB.FileStorage:411][MainThread] Ignoring index for /<path-to-project>/my_project/project-title/backend/instance/var/filestorage/Data.fs
2022-09-24 01:30:19,639 INFO [chameleon.config:38][MainThread] directory cache: /<path-to-project>/my_project/project-title/backend/instance/var/cache.
2022-09-24 01:30:23,680 INFO [plone.volto:22][MainThread] Aliasing collective.folderish classes to plone.volto classes.
2022-09-24 01:30:24,935 INFO [Zope:42][MainThread] Ready to handle requests
Starting server in PID 92714.
2022-09-24 01:30:24,940 INFO [waitress:486][MainThread] Serving on http://[::1]:8080
2022-09-24 01:30:24,940 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080
Start Plone frontend#
Create a second shell session in a new window.
Change your current working directory to project-title
.
Start the Plone frontend with the following command.
make start-frontend
The Plone frontend server starts up and emits messages to the console.
WAIT Compiling...
✔ Client
Compiled successfully in 864.83ms
✔ Server
Compiled successfully in 9.62s
✅ Server-side HMR Enabled!
sswp> Handling Hot Module Reloading
Volto is running in SEAMLESS mode
Using internal proxy: http://localhost:3000 -> http://localhost:8080/Plone
🎭 Volto started at 0.0.0.0:3000 🚀
Note that the Plone frontend uses an internal proxy server to connect with the Plone backend. Open a browser at the following URL to visit your Plone site.
You will see a page similar to the following.
Select the Login link to visit the login form, and enter the following credentials.
Login name:
admin
Password:
admin
Now you can edit content or configure your Plone site.
You can stop the site with ctrl-c.