You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Please fill this form](https://forms.gle/npDRESAud4ntDnUz7).
11
13
12
14
Plone offers a wealth of features right out of the box. You can extend these capabilities using {term}`TTW` modifications, such as creating new content types, altering the default workflow, or configuring the top-level navigation. For additional functionalities not covered by Plone, you can either develop your own solutions or integrate existing add-ons.
13
15
14
16
## Project packages
15
17
16
-
A Plone project is composed by, at least, a backend Python package and a frontend ReactJS package. These packages, generated for you during the creation of the codebase, are responsible for configuring the project and integrating third-party add-ons.
18
+
A Plone project is composed by, at least, a backend Python package and a frontend React package. These packages, generated for you during the creation of the code base, are responsible for configuring the project and integrating third-party add-ons.
17
19
18
20
The packages for this training are:
19
21
20
-
-**ploneconf2025.core**: Package metadata located at `backend/pyproject.toml` and code at `backend/src/ploneconf2025/core`.
21
-
-**volto-ploneconf2025-core**: Package metadata located at `frontend/packages/volto-ploneconf2025-core/package.json` and code at `frontend/packages/volto-ploneconf2025-core/src`.
22
+
`ploneconf2025.core`
23
+
: Package metadata located at {file}`backend/pyproject.toml` and code at {file}`backend/src/ploneconf2025/core`.
24
+
25
+
`volto-ploneconf2025-core`
26
+
: Package metadata located at {file}`frontend/packages/volto-ploneconf2025-core/package.json` and code at {file}`frontend/packages/volto-ploneconf2025-core/src`.
22
27
23
-
## Integrating Add-ons
28
+
## Integrate add-ons
24
29
25
-
Both Plone Frontend and Backend in your project support add-on integration. Add-ons can be specific to either the Frontend or Backend, or they can be collaborative packages enhancing both components.
30
+
Both Plone frontend and backend in your project support add-on integration. Add-ons can be specific to either the frontend or backend, or they can be collaborative packages enhancing both components.
26
31
27
-
-**Plone Backend Add-ons**: These are Python packages available on PyPI. [Awesome Plone](https://github.com/collective/awesome-plone) offers a curated list of these add-ons.
28
-
-**Plone Frontend Add-ons**: Written in JavaScript or TypeScript, these are released as NPM packages. Check out [Awesome Volto](https://github.com/collective/awesome-volto) for a collection of Frontend add-ons.
32
+
Plone backend add-ons
33
+
: These are Python packages available on PyPI.
34
+
[Awesome Plone](https://github.com/collective/awesome-plone) offers a curated list of these add-ons.
29
35
30
-
### Changing the default theme
36
+
Plone frontend add-ons
37
+
: Written in JavaScript or TypeScript, these are released as npm packages.
38
+
Check out [Awesome Volto](https://github.com/collective/awesome-volto) for a collection of frontend add-ons.
39
+
40
+
### Change the default theme
31
41
32
42
We'll illustrate the process of integrating an add-on named `Volto Light Theme`, which provides a new theme for Volto. This add-on is composed by a frontend component, named `@kitconcept/volto-light-theme`, and a backend component named `kitconcept.voltolighttheme`.
33
43
34
-
#### Backend: Incorporating a New Dependency
44
+
#### Backend: incorporate a new dependency
35
45
36
46
First, we need to add the package as a dependency on the Python project by editing {file}`backend/pyproject.toml` and append `kitconcept.voltolighttheme` to the `dependencies` section. This will ensure the add-on will be available to Python.
37
47
38
-
Then we tell Zope to load the add-on run-time configurations by editing {file}`backend/src/ploneconf2025/core/dependencies.zcml` and append `kitconcept.voltolighttheme`
48
+
```{code-block} toml
49
+
:emphasize-lines: 6
50
+
:caption: {file}`backend/pyproject.toml`
51
+
52
+
dependencies = [
53
+
"Products.CMFPlone==6.1.3",
54
+
"plone.api",
55
+
"plone.restapi",
56
+
"plone.volto",
57
+
"kitconcept.voltolighttheme",
58
+
]
59
+
```
39
60
40
-
And, if we want to have this add-on installed when we create a new website, edit {file}`backend/src/ploneconf2025/core/profiles/default/metadata.xml` and append `kitconcept.voltolighttheme`
61
+
Then we tell Zope to load the add-on run-time configurations by editing {file}`backend/src/ploneconf2025/core/dependencies.zcml` and append `kitconcept.voltolighttheme`.
And, if we want to have this add-on installed when we create a new website, edit {file}`backend/src/ploneconf2025/core/profiles/default/metadata.xml` and append `profile-kitconcept.voltolighttheme:default`.
Edit {file}`frontend/packages/volto-ploneconf2025/package.json` and append `@kitconcept/volto-light-theme` to the `addons` and `dependencies` sections, as shown below:
To ensure the behaviors manually applied to the Plone Site persist after the site is re-created, we need to add them via Generic Setup.
94
146
@@ -115,7 +167,7 @@ Create a new file {file}`backend/src/ploneconf2025/core/profiles/default/types/P
115
167
</object>
116
168
```
117
169
118
-
## Modifying the default content
170
+
## Modify the default content
119
171
120
172
As you can see, the default content available just after the site creation is generic, but we can change that as well.
121
173
@@ -126,7 +178,7 @@ cd backend
126
178
make update-example-content
127
179
```
128
180
129
-
Now, if you run `git status` you should see changes to files under `backend/src/ploneconf2025/core/setuphandlers/examplecontent`. This is location where `plone.exportimport` will look for the content to be to your Plone site upon creation.
181
+
Now, if you run `git status` you should see changes to files under {file}`backend/src/ploneconf2025/core/setuphandlers/examplecontent`. This is the location where `plone.exportimport` will look for the content to be for your Plone site upon creation.
130
182
131
183
Now we are going to add these changes to our repository by running:
Copy file name to clipboardExpand all lines: docs/plone-deployment/project-new.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -133,7 +133,7 @@ make install
133
133
134
134
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.
135
135
136
-
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 {file}`pyproject.toml` file. Or you can create a {file}`.python-version` file in the {file}`backend` folder.
136
+
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 {file}`pyproject.toml` file.
137
137
138
138
Putting too specific Node.js and Python versions in the scaffolded project setup can cause other issues.
139
139
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.
Copy file name to clipboardExpand all lines: docs/plone-deployment/project-start.md
+35-35Lines changed: 35 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,82 +1,82 @@
1
1
---
2
2
myst:
3
3
html_meta:
4
-
"description": "Guidance on initiating your new project locally"
5
-
"property=og:description": "Step-by-step instructions to start your Plone project on your local machine."
6
-
"property=og:title": "Launching Your Plone Project Locally"
7
-
"keywords": "Plone, Deployment, Ansible, Docker, GitHub, Local Development"
4
+
"description": "Guide to start your Plone project on your local machine"
5
+
"property=og:description": "Guide to start your Plone project on your local machine"
6
+
"property=og:title": "Guide to start your Plone project on your local machine"
7
+
"keywords": "Plone, deployment, Ansible, Docker, GitHub, local development"
8
8
---
9
9
10
-
# Start the Project
10
+
# Start the project
11
11
12
-
The {term}`cookieplone` equips you with essential tools to initiate a local development environment. {doc}`project-new` offers two methods to launch your project: manually starting the Backend and Frontend servers, or utilizing a Docker Compose stack.
12
+
{term}`Cookieplone` equips you with essential tools to initiate a local development environment. {doc}`project-new` offers two methods to launch your project: manually starting the backend and frontend servers, or utilizing a Docker Compose stack.
13
13
14
-
## Running Local Servers
14
+
## Run local servers
15
15
16
-
This method requires two terminals as both Backend and Frontend operate in "foreground mode". It's optimal for local development due to its swift change and restart cycle. However, accessing each server on their internal ports can lead to CORS issues in real-world deployments.
16
+
This method requires two terminal sessions, as both backend and frontend operate in "foreground mode". It's optimal for local development due to its swift change and restart cycle. However, accessing each server on their internal ports can lead to CORS issues in real-world deployments.
17
17
18
-
### Starting the Backend
18
+
### Start the backend
19
19
20
20
Navigate to the project's root folder and execute:
21
21
22
22
```shell
23
23
make backend-start
24
24
```
25
25
26
-
This command initiates the Backend server. Upon successful startup, you'll observe:
26
+
This command initiates the backend server. Upon successful startup, you'll observe:
27
27
28
28
```console
29
29
... INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080
30
30
```
31
31
32
-
Indicating the server is operational and awaiting requests on port 8080. Visit http://localhost:8080 to explore.
32
+
The above indicates that the server is operational and awaiting requests on port 8080. Visit http://localhost:8080 to explore.
33
33
34
34
```{figure} _static/start_backend_localhost.png
35
-
:alt: Backend server initiation at http://localhost:8080
35
+
:alt: Backend server initiation at `http://localhost:8080`
36
36
37
-
Backend server initiation at http://localhost:8080
37
+
Backend server initiation at `http://localhost:8080`
38
38
```
39
39
40
40
41
-
### Starting the Frontend
41
+
### Start the frontend
42
42
43
43
In a new terminal at the project root, execute:
44
44
45
45
```shell
46
46
make frontend-start
47
47
```
48
48
49
-
The Frontend initiation takes longer due to the initial codebase compilation for both the NodeJS server as the browser javascript bundles. A successful startup displays:
49
+
The frontend initiation takes longer, due to the initial code base compilation for both the Node.js server for the browser JavaScript bundles. A successful startup displays:
50
50
51
-
```
51
+
```console
52
52
🎭 Volto started at 0.0.0.0:3000 🚀
53
53
```
54
54
55
-
Signifying the Frontend server is active on port 3000. Access it via http://localhost:3000.
55
+
The above signifies that the frontend server is active on port 3000. Access it via http://localhost:3000.
56
56
57
57
```{figure} _static/start_frontend_localhost.png
58
-
:alt: Frontend server initiation at http://localhost:3000
58
+
:alt: Frontend server initiation at `http://localhost:3000`
59
59
60
-
Frontend server initiation at http://localhost:3000
60
+
Frontend server initiation at `http://localhost:3000`
61
61
```
62
62
63
63
```{note}
64
64
Default credentials: **admin/admin**.
65
65
```
66
66
67
-
## Stopping the servers
67
+
## Stop the servers
68
68
69
69
In both terminals, press {kbd}`Ctrl-C`.
70
70
71
-
## Running Docker Compose
71
+
## Run Docker Compose
72
72
73
-
Docker Compose is suitable for reviewing your development progress or exploring the project. It comprises four services: {term}`Traefik` web server, Frontend, Backend, and a `Postgres` database, mimicking a production environment.
73
+
Docker Compose is suitable for reviewing your development progress or exploring the project. It comprises four services: {term}`Traefik` web server, frontend, backend, and a PostgreSQL database, mimicking a production environment.
74
74
75
75
```{note}
76
-
A secondary Backend route, `/ClassicUI`, mirrors `http://localhost:8080/Plone`. It's secured with Basic Authentication, default credentials being **admin/admin**.
76
+
A secondary backend route, `/ClassicUI`, mirrors `http://localhost:8080/Plone`. It's secured with basic authentication, default credentials being **admin/admin**.
77
77
```
78
78
79
-
### Starting the Stack
79
+
### Start the Stack
80
80
81
81
Ensure port 80 is free, then initiate the stack with:
82
82
@@ -94,41 +94,41 @@ Verify the stack's operational status with:
94
94
make stack-status
95
95
```
96
96
97
-
Initially, the Frontend may display an **(unhealthy)** status due to the absence of a created Plone site.
97
+
Initially, the frontend may display an **(unhealthy)** status due to the absence of a created Plone site.
98
98
99
-
### Creating a New Plone Site
99
+
### Create a new Plone site
100
100
101
-
Initiate a new Plone site within the Docker Compose Stack by executing:
101
+
Initiate a new Plone site within the Docker Compose stack by executing:
102
102
103
103
```shell
104
104
make stack-create-site
105
105
```
106
106
107
-
Re-run `make stack-status`, and both Backend and Frontend should now display a **(healthy)** status.
107
+
Re-run `make stack-status`, and both backend and frontend should now display a **(healthy)** status.
108
108
109
-
### Accessing the Site
109
+
### Accessing the site
110
110
111
111
Your website is accessible at http://ploneconf2025.localhost.
112
112
113
113
```{figure} _static/start_stack_localhost.png
114
-
:alt: Accessing the site at http://ploneconf2025.localhost
114
+
:alt: Accessing the site at `http://ploneconf2025.localhost`
115
115
116
-
Accessing the site at http://ploneconf2025.localhost
116
+
Accessing the site at `http://ploneconf2025.localhost`
117
117
```
118
118
119
-
### Updating the Codebase
119
+
### Updating the code base
120
120
121
121
For codebase modifications, re-run `make stack-start` to rebuild the affected containers, ensuring your site's behavior aligns with the updates.
122
122
123
-
### Stopping the Stack
123
+
### Stop the stack
124
124
125
-
To halt the stack while preserving site data, execute:
125
+
To stop the stack while preserving site data, execute:
126
126
127
127
```shell
128
128
make stack-stop
129
129
```
130
130
131
-
### Removing the Stack
131
+
### Removing the stack
132
132
133
133
To dismantle the stack and erase all site data, use:
Your Plone project's generated codebase includes a {file}`/devops/ansible` folder, equipped with tools for provisioning and setting up a basic server installation. We'll utilize **Ansible** for automation, **Docker** for containerization, and **Docker Swarm** for enhanced scalability and availability.
12
+
Your Plone project's generated code base includes a {file}`/devops/ansible` folder, equipped with tools for provisioning and setting up a basic server installation. We'll utilize **Ansible** for automation, **Docker** for containerization, and **Docker Swarm** for enhanced scalability and availability.
13
13
14
-
## Navigating to Devops
14
+
## Navigating to `devops`
15
15
16
16
Start by changing your directory to {file}`devops/ansible`:
17
17
18
18
```shell
19
19
cd devops/ansible
20
20
```
21
21
22
-
## Configuring the Environment
22
+
## Configure the environment
23
23
24
24
Create a new {file}`.env` file by copying the content from the existing `.env_dist` file:
The {file}`.env` file is listed in {file}`.gitignore` to prevent pushing environment-specific configurations to the repository.
43
43
```
44
44
45
-
## Installing Ansible
45
+
## Install Ansible
46
46
47
47
Run the following command to create a Python 3 virtual environment and install Ansible with its dependencies:
48
48
49
49
```shell
50
50
make install
51
51
```
52
52
53
-
## Configuring the Inventory
53
+
## Configure the inventory
54
54
55
-
Update the {file}`devops/ansible/inventory/hosts.ym` file with the appropriate server details:
55
+
Update the {file}`devops/ansible/inventory/hosts.yml` file with the appropriate server details:
56
56
57
57
```yaml
58
58
---
@@ -70,8 +70,7 @@ cluster:
70
70
```
71
71
72
72
73
-
74
-
## Initiating Server Setup
73
+
## Initiate server setup
75
74
76
75
With the correct information in {file}`devops/ansible/inventory/hosts.yml`, test the connection to the server with:
77
76
@@ -87,7 +86,7 @@ uv run ansible-playbook playbooks/setup.yml
87
86
88
87
This command executes the Ansible playbook {file}`devops/playbooks/setup.yml` performing tasks like installing base packages, creating a user, setting up SSH, and initializing Docker Swarm on the remote server:
89
88
90
-
## Verifying Remote Server Access
89
+
## Verify remote server access
91
90
92
91
You should now be able to SSH into the remote server as both **root** and **plone** users:
0 commit comments