Create a project with Volto (development or pre-release)#

This chapter describes how you can create a web application using the latest development release version of Plone with Volto 18 or later for the frontend, while having full control over its development and deployment.

See also

For other installation options, see Install.

New in version Volto: 18.0.0-alpha.43

Cookieplone is now the method to create a Plone project with unstable versions of Volto, version 18.0.0-alpha.43 and above.

System requirements#

Plone 6 has both hardware requirements and software prerequisites.

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 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.

pipx#

Install pipx.

pip install pipx

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.

  1. Create your shell profile, if it does not exist.

    touch ~/.bash_profile
    
  2. Download and run the nvm install and update script, and pipe it into bash.

    curl -o- https://raw.githubusercontent.com/creationix/nvm/v{NVM_VERSION}/install.sh | bash
    
  3. Source your profile. Alternatively close the session and open a new one.

    source ~/.bash_profile
    
  4. Verify that the nvm version is that which you just installed or updated:

    nvm --version
    

Node.js#

  1. Install or update the supported LTS versions of Node.js, then activate the version supported in Volto.

    nvm install --lts
    nvm use --lts
    
  2. Verify that the supported version of Node.js is activated.

    node -v
    
  1. Enable corepack so that Node.js will install pnpm as a package manager.

    corepack enable
    

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.

Git#

Install git for your operating system.

Generate the project#

After satisfying the prerequisites and having activated an LTS version of Node, generate the project.

pipx run cookieplone project

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 cookieplone project
╭──────────────────────────────── cookieplone ────────────────────────────────╮
│                                                                             │
│                              .xxxxxxxxxxxxxx.                               │
│                          ;xxxxxxxxxxxxxxxxxxxxxx;                           │
│                       ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx;                        │
│                     xxxxxxxxxx              xxxxxxxxxx                      │
│                   xxxxxxxx.                    .xxxxxxxx                    │
│                  xxxxxxx      xxxxxxx:            xxxxxxx                   │
│                :xxxxxx       xxxxxxxxxx             xxxxxx:                 │
│               :xxxxx+       xxxxxxxxxxx              +xxxxx:                │
│              .xxxxx.        :xxxxxxxxxx               .xxxxx.               │
│              xxxxx+          ;xxxxxxxx                 +xxxxx               │
│              xxxxx              +xx.                    xxxxx.              │
│             xxxxx:                      .xxxxxxxx       :xxxxx              │
│             xxxxx                      .xxxxxxxxxx       xxxxx              │
│             xxxxx                      xxxxxxxxxxx       xxxxx              │
│             xxxxx                      .xxxxxxxxxx       xxxxx              │
│             xxxxx:                      .xxxxxxxx       :xxxxx              │
│             .xxxxx              ;xx.       ...          xxxxx.              │
│              xxxxx+          :xxxxxxxx                 +xxxxx               │
│              .xxxxx.        :xxxxxxxxxx               .xxxxx.               │
│               :xxxxx+       xxxxxxxxxxx              ;xxxxx:                │
│                :xxxxxx       xxxxxxxxxx             xxxxxx:                 │
│                  xxxxxxx      xxxxxxx;            xxxxxxx                   │
│                   xxxxxxxx.                    .xxxxxxxx                    │
│                     xxxxxxxxxx              xxxxxxxxxx                      │
│                       ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+                        │
│                          ;xxxxxxxxxxxxxxxxxxxxxx;                           │
│                              .xxxxxxxxxxxxxx.                               │
│                                                                             │
╰─────────────────────────────────────────────────────────────────────────────╯
You've downloaded /Users/stevepiercy/.cookiecutters/cookieplone-templates 
before. Is it okay to delete and re-download it? [y/n] (y): 
╭─────────────────────────────── Plone Project ───────────────────────────────╮
│ Creating a new Plone Project                                                │
╰─────────────────────────────────────────────────────────────────────────────╯
  [1/17] Project Title (Project Title): 
  [2/17] Project Description (A new project using Plone 6.): 
  [3/17] Project Slug (Used for repository id) (project-title): 
  [4/17] Project URL (without protocol) (project-title.example.com): 
  [5/17] Author (Plone Foundation): 
  [6/17] Author E-mail (collective@plone.org): 
  [7/17] Should we use prerelease versions? (No): 
  [8/17] Plone Version (6.0.13): 
  [9/17] Volto Version (18.0.0-alpha.43):
  [10/17] Python Package Name (project.title):
  [11/17] Volto Addon Name (volto-project-title): 
  [12/17] 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): 
  [13/17] GitHub or GitLab Username or Organization (collective): 
  [14/17] Container Registry
    1 - GitHub Container Registry
    2 - Docker Hub
    3 - GitLab
    Choose from [1/2/3] (1): 
  [15/17] Should we setup a caching server?
    1 - Yes
    2 - No
    Choose from [1/2] (1): 
  [16/17] Add Ansible playbooks?
    1 - Yes
    2 - No
    Choose from [1/2] (1): 
  [17/17] Add GitHub Action to Deploy this project?
    1 - Yes
    2 - No
    Choose from [1/2] (1): 
╭───────────────────────── Project Title generation ──────────────────────────╮
│                                                                             │
│ Summary:                                                                    │
│                                                                             │
│   - Plone version: 6.0.13                                                   │
│   - Volto version: 18.0.0-alpha.43                                          │
│   - Output folder:                                                          │
│ <PATH_TO>/project-title                                                     │
│                                                                             │
│                                                                             │
╰─────────────────────────────────────────────────────────────────────────────╯
 -> Initialize Git repository
 -> Setup Backend
 -> Setup Frontend
 -> Setup Cache
 -> Setup Project Settings
╭───────────────────────── New project was generated ─────────────────────────╮
│                                                                             │
│ Project Title                                                               │
│                                                                             │
│ Now, code it, create a git repository, push to your organization.           │
│                                                                             │
│ Sorry for the convenience,                                                  │
│ The Plone Community.                                                        │
│                                                                             │
│ https://plone.org/                                                          │
╰─────────────────────────────────────────────────────────────────────────────╯

Install the project#

To work on your project, you need to install both the frontend and backend.

Change your current working directory to project-title.

cd project-title

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, then you need to install Pillow's dependencies.

brew install zlib libjpeg
apt-get zlib libjpeg

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.

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 backend-start

The Plone backend server starts up and emits messages to the console.

2024-09-25 16:47:15,699 INFO    [chameleon.config:39][MainThread] directory cache: /<path-to-project>/backend/instance/var/cache.
2024-09-25 16:47:16,387 WARNING [ZODB.FileStorage:412][MainThread] Ignoring index for /<path-to-project>/backend/instance/var/filestorage/Data.fs
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.
2024-09-25 16:47:17,018 INFO    [plone.volto:23][MainThread] Aliasing collective.folderish classes to plone.volto classes.
2024-09-25 16:47:17,760 INFO    [Zope:42][MainThread] Ready to handle requests
Starting server in PID 20912.
2024-09-25 16:47:17,772 INFO    [waitress:486][MainThread] Serving on http://[::1]:8080
2024-09-25 16:47:17,772 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 frontend-start

The Plone frontend server starts up and emits messages to the console, and should end with the following.

webpack 5.90.1 compiled successfully in 11004 ms
sswp> Handling Hot Module Reloading
Using volto.config.js in: /<path-to-project>/frontend/volto.config.js
✅  Server-side HMR Enabled!
Volto is running in SEAMLESS mode
Proxying API requests from http://localhost:3000/++api++ to 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.

http://localhost:3000

You will see a page similar to the following.

Plone home page

Select the Login link to visit the login form, and enter the following credentials.

  • Login name: admin

  • Password: admin

Plone login page

Now you can edit content or configure your Plone site.

You can stop the site with ctrl-c.