Create a new project – Plone deployment

Create a new project

Create a new project#

As highlighted in the Introduction's Training choices, GitHub is essential for building Docker images automatically in this training. The steps can be adapted for other providers, including GitLab.

Generate the codebase#

Note

This training session as of October 2025 will use an experimental branch of cookieplone-templates.

Execute cookieplone to generate a Plone project skeleton with the command below.

COOKIEPLONE_REPOSITORY_TAG=project-profiles uvx cookieplone project

Answer the prompts as they appear. You can either accept the default values or enter your own.

Warning

For participants in the Plone Conference 2025 Training sessions in Jyväskylä, Finland, please use at least the following settings:

Project Title: Plone Conference Training
Project Slug: ploneconf2025
Project URL: ploneconf2025-<your-github-username>.tangrama.com.br
Should we use prerelease versions?: Y(es)
Volto Version: 19.0.0-alpha.6
Python Package Name: ploneconf2025.core
Language: 1
GitHub or GitLab username or organization slug from URL: <your-github-username>
URL to the repository: https://github.com/<your-github-username>/ploneconf2025
GitHub Container Registry: 1 - GitHub Container Registry
Which persistent storage to use in the deployment stack?: 1 - RelStorage with PostgreSQL
Should we setup a caching server: Y(es)
Add Ansible playbooks?: Y(es)
Add GitHub Action to Deploy this project?: Y(es)
Would you like to add a documentation scaffold to your project?: Y(es)

An example interaction with the Cookieplone wizard is shown below:

  [1/20] Project Title (Project Title): Plone Conference Training
  [2/20] Project Description (A new project using Plone 6.):
  [3/20] Project Slug (Used for repository id) (plone-conference-training): ploneconf2025
  [4/20] Project URL (without protocol) (ploneconf2025.example.com): ploneconf2025-<your-github-username>.tangrama.com.br
  [5/20] Author (Plone):
  [6/20] Author E-mail (collective@plone.org):
  [7/20] Should we use prerelease versions? (No): Yes
  [8/20] Plone Version (6.1.3):
  [9/20] Volto Version (19.0.0-alpha.6):
  [10/20] Python Package Name (ploneconf2025): ploneconf2025.core
  [11/20] Volto Addon Name (volto-ploneconf2025-core):
  [12/20] Language
    1 - English
    2 - Deutsch
    3 - Español
    4 - Português (Brasil)
    5 - Nederlands
    6 - Suomi
    7 - Italiano
    8 - Svenska
    Choose from [1/2/3/4/5/6/7/8] (1):
  [13/20] GitHub or GitLab username or organization slug from URL (collective): <your-github-username>
  [14/20] URL to the repository (https://github.com/<your-github-username>/ploneconf2025):
  [15/20] Container Registry
    1 - GitHub Container Registry
    2 - Docker Hub
    3 - GitLab
    Choose from [1/2/3] (1):
  [16/20] Which persistent storage to use in the deployment stack?
    1 - RelStorage with PostgreSQL (recommended)
    2 - ZEO with FileStorage
    3 - Local FileStorage, implies a single backend
    Choose from [1/2/3] (1):
  [17/20] Should we setup a caching server?
    1 - Yes
    2 - No
    Choose from [1/2] (1):
  [18/20] Add Ansible playbooks?
    1 - Yes
    2 - No
    Choose from [1/2] (1):
  [19/20] Add GitHub Action to Deploy this project?
    1 - Yes
    2 - No
    Choose from [1/2] (1):
  [20/20] Would you like to add a documentation scaffold to your project?
    1 - Yes
    2 - No
    Choose from [1/2] (1):

Navigate to your project directory:

cd ploneconf2025

Understanding the code base#

/.github/workflows: Contains GitHub Actions workflows for code testing and container image release.
/backend: Holds the backend (API) solution with Python code base located in src/plone_conference.
/frontend: Contains the frontend (Volto) solution generated by @plone/generator-volto.
/devops: Stores Ansible and Docker stacks.
/Makefile: Defines tasks for code base management.

We employ make for its reliability, widespread availability, and maturity. Future plans include enhancing make's dependency management and capabilities.

View all available commands and descriptions with:

make help

Installing the code base and dependencies#

Install both the Plone backend and frontend with:

make install

This process will take a few minutes. Once completed, a success message will appear. Both the frontend and backend in their respective directories will be built.

For the frontend, the Node.js version will be used that you activated in the previous chapter with nvm use --lts. For the backend Python version, uv will check a requires-python key in the pyproject.toml file.

Putting too specific Node.js and Python versions in the scaffolded project setup can cause other issues. That's why the project generator gives hints for versions with ranges or LTS. But it is your own choice and responsibility to check for the correct major versions of both programming languages are active and available before you run make install in the project root or frontend and backend subdirectories for the first time.

Code formatting and i18n#

Ensure all tests pass on GitHub Actions after pushing the repository by running:

make check

Also update all the translation files by running:

make i18n

Create a repository on GitHub#

Warning

You must either have a public repository, or a GitHub Team plan or a GitHub Pro plan for a private repository. Otherwise you will not see the Environment option in Settings, which is required for setting up the secrets and variables for the GitHub Actions.`

2. Create a new repository#

Click the + icon in the upper right corner, select New repository, and fill in the details:

Repository name: ploneconf2025
Description: Plone Conference 2025 Training
Visibility: Public

Click Create repository.

Initialize and push to the Git repository#

1. Initialize your project#

Cookieplone already initializes a Git repository for you. Make sure that you ran make check and make i18n.

2. Add files#

Stage changes to commit in the current directory. Staging lets you select which changes you want to commit.

git add .

3. Initial commit#

Save the staged changes, along with a brief log message describing the changes. Replace Initial commit with a descriptive message, if needed. For the first commit, we typically label it as Initial commit.

git commit -m "Initial commit"

4. Link local repository to remote repository#

Connect your local repository to the remote server. First replace <your-github-username> with your actual GitHub username. origin is the default name given to the remote repository. Also set the default branch to main.

git remote add origin git@github.com:<your-github-username>/ploneconf2025.git
git branch -M main

5. Push to GitHub#

Push your commits to the remote repository hosted on GitHub. This command will trigger the GitHub Actions that test the codebase and generate Docker images for the backend and for the frontend.

git push -u origin main