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 like GitLab.

Generating the Codebase#

Execute cookiecutter to generate a Plone project skeleton using the Cookiecutter cookiecutter-plone-starter with the command below.

pipx run cookiecutter gh:collective/cookiecutter-plone-starter

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

Warning

For participants of Plone Conference 2023, please use the following settings:

Project Title: Plone Conference Training
Project Slug: ploneconf2023
Project URL: ploneconf2023-<your-github-username>.tangrama.com.br
GitHub Username or Organization: <your-github-username>

An example interaction with the cookiecutter-plone-starter wizard is shown below:

  [1/18] Project Title (Project Title): Plone Conference Training
  [2/18] Project Description (A new project using Plone 6.):
  [3/18] Project Slug (Used for repository id) (plone-conference-training): ploneconf2023
  [4/18] Project URL (without protocol) (ploneconf2023.example.com): ploneconf2023-<your-github-username>.tangrama.com.br
  [5/18] Author (Plone Foundation): Your Name
  [6/18] Author E-mail (collective@plone.org): <your-github-username>@plone.org
  [7/18] Python Package Name (ploneconf2023):
  [8/18] Volto Addon Name (volto-ploneconf2023):
  [9/18] Choose a Python Test Framework
    1 - pytest
    2 - unittest
    Choose from [1/2] (1):
  [10/18] Plone Version (6.0.7):
  [11/18] Should we use Volto Alpha Versions? (Yes):
  [12/18] Volto Version (17.0.0):
  [13/18] Volto Generator Version (7.0.1):
  [14/18] 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/18] GitHub Username or Organization (collective): <your-github-username>
  [16/18] Container Registry
    1 - GitHub Container Registry
    2 - Docker Hub
    Choose from [1/2] (1):
  [17/18] Add Ansible playbooks?
    1 - Yes
    2 - No
    Choose from [1/2] (1):
  [18/18] Add GitHub Action to Deploy this project?
    1 - Yes
    2 - No
    Choose from [1/2] (1):

Navigate to your project directory:

cd ploneconf2023

Understanding the Codebase#

/.github/workflows: Contains GitHub Actions workflows for code testing and container image release.
/backend: Holds the backend (API) solution with Python codebase 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 codebase 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 Codebase 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.

Code Formatting and i18n#

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

make format

Due to output differences in translations built by @plone/generator-volto, execute the following in the root directory:

make i18n

Create a Repository on GitHub#

2. Create a New Repository#

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

Repository name: ploneconf2023
Description: Plone Conference 2023 Training
Visibility: Public

Click 'Create repository'.

Initialize and Push to the Git Repository#

1. Initialize Git#

Initializes a new Git repository and begins tracking an existing directory.

git init .

2. Add Files#

stages changes for commit, meaning it tracks the new files (in this case, all files in the directory with .). Staging lets you select which changes you want to commit.

git add .

3. Initial Commit#

Saves the staged changes along with a brief log message describing the changes. Replace "Initial commit" with a descriptive message if needed. It's the first commit, so we typically label it as the "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, and we also set the default branch to be main.

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

4. 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