Create and install an environment for volto development on a linux machine (debian based)

How to bootstrap a volto project

Install Node package manager (npm). It is the tool required to install JavaScript packages and libraries:

sudo apt install npm

Install Node version manager (nvm). Volto frontend requires a Node.js server for resource delivery and server side rendering. Node version manager is a tool which helps running the version of Node.js required by Volto:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

Install and use Node.js in the required version. At the time of writing this document, this is 16.x:

nvm install 16
nvm use 16

Install npm packages required to bootstrap a Volto project. The installation of the JavaScript packages is done locally, not system wide. This way we avoid potential conflicts if other projects require e.g. a differing set of installed package versions to run.:

npm install --prefix . \
    yarn \
    yo \
    @plone/generator-volto

Since we installed NPM packages locally, we want to extend the PATH for convenient access to the installed terminal commands:

export PATH=$PATH:$(pwd)/node_modules/.bin

Use yo to call the volto generator. It generates the directory structure for our Volto frontend:

yo @plone/volto

While yo runs, you get asked some questions. Answer them as follows:

Project name (e.g. my-volto-project) frontend
Would you like to add addons? false

Install backend server. The backend server provides the actual database and REST endpoints used by Volto. The following steps create a Python virtual environment, generate a Makefile and install and start Zope/Plone:

mkdir backend
cd backend
python3 -m venv venv
./venv/bin/pip install https://github.com/mxstack/mxmake/archive/develop.zip
./venv/bin/mxmake init

mxmake init fires an interactive terminal session. Once asked, choose:

[?] Include topics:
    [X] applications
    [X] core
[?] Include domains from topic "applications":
    [X] applications.cookiecutter
    [X] applications.zope
[?] Include domains from topic "core":
    [X] core.base
    [X] core.mxenv
    [X] core.mxfiles
    [X] core.packages
    [ ] core.sources

Hit enter until done to accept all defaults.

Create requirements.txt. It contains the Python packages to be installed. Plone is a policy package handling all the requirements needed to run the backend server:

echo "Plone" > requirements.txt

Create an instance.yaml. It contains required configuration for running the Zope server. Once mxmake handles the initial creation of this file properly, this stept is not necessary any more.

The minimal information to be conained in instance.yaml:

default_context:
    initial_user_name: 'admin'
    initial_user_password: 'admin'
    db_storage: direct

Run make to install the backend server:

make install

Open a dedicated terminal and run the backend server:

make zope-start

Connect to your zope instance to localhost:8080 and create a plone Site under path Plone.

Start frontend node server in a dedicated terminal:

cd frontend
yarn install
yarn start

Start Developing

Structure (Points of interest):

frontend
- omlette (-> node_modules/@plone/volto)
  
  Handy link to see how things are done.
- src (Containing our react/JS development code)
- theme (Includes all CSS, LESS, fonts, etc...)
  
  globals (Not exists initially, contains variables)
- public (Static serverd folder, contains robots.txt, favicon)

Examples of theme customization

Changing variables

Create theme/globals/site.variables (it is a LESS file) contaning:

@fontName: 'FreeMono'

Note

Every time you create a file in the themes folder, the frontend server must be restarted.

Note

To get an overview which variables are to be overwritten, take a look at omelette/theme/themes/default/globals/site.variables.

Adding custom styles

Create theme/extras/custom.overrides and restart frontend.

This file contains custom LESS code.

Replace the logo

In volto, we are able to override virtually every file within src with a custom version. This is called component shadowing.

Files to shadow are best located via the omelette convenience location.

The logo file we need to override is located at src/components/theme/Logo/Logo.svg.

Our component shadowing root is src/customizations where the target structure gers replicated with the files we want to override. This works for all files types.

So, to finally customize the logo, we create src/customizations/components/theme/Logo/Logo.svg with the custom logo image we want to use.