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#
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.
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 (firstname.lastname@example.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:
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
/frontend: Contains the frontend (Volto) solution generated by
/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:
Installing the Codebase and Dependencies#
Install both the Plone backend and frontend with:
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:
Due to output differences in translations built by
@plone/generator-volto, execute the following in the root directory:
Create a Repository on GitHub#
1. Login to GitHub#
Visit GitHub and log in.
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
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.
"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. 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