Skip to content

Commit db72081

Browse files
stevepiercystevepiercy
committed
Final polish of Deployment docs
1 parent df9df97 commit db72081

1 file changed

Lines changed: 78 additions & 55 deletions

File tree

‎docs/plone-deployment/deploy.md‎

Lines changed: 78 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,39 @@
11
---
22
myst:
33
html_meta:
4-
"description": "Learn how to deploy Plone using make, GitHub Actions, or Gitlab CI with ease."
5-
"property=og:description": "A comprehensive guide to deploying Plone via various methods."
6-
"property=og:title": "Efficiently Deploy Plone: A Step-by-Step Guide"
7-
"keywords": "Deploy, Plone, Makefile, GitHub Actions, Gitlab CI"
4+
"description": "How to deploy a Plone project using make, GitHub Actions, or Gitlab CI"
5+
"property=og:description": "How to deploy a Plone project using make, GitHub Actions, or Gitlab CI"
6+
"property=og:title": "How to deploy a Plone project using make, GitHub Actions, or Gitlab CI"
7+
"keywords": "deploy, Plone, Makefile, GitHub Actions, GitLab CI"
88
---
99

10-
# Deploying the Project
10+
# Deploy the project
1111

12-
## Project Stack
12+
## Project stack
1313

1414
This guide outlines the steps to deploy the project using a Docker stack comprising:
1515

16-
- **Traefik:** A router and SSL termination tool, integrated with [Let's Encrypt](https://letsencrypt.org/) for complimentary SSL certificates.
17-
- **Plone Frontend using Volto:** A service based on React for the frontend.
18-
- **Plone Backend:** The API service.
19-
- **Postgres 14 Database:** Handles data persistence.
16+
Traefik
17+
: A router and TLS termination tool, integrated with [Let's Encrypt](https://letsencrypt.org/) for complimentary secure certificates.
2018

21-
You can find this stack at {file}`devops/stacks/ploneconf2025-<your-github-username>.tangrama.com.br.yml`. It's modular, allowing easy integration of additional services like {term}`Varnish`, `Solr`, or `ElasticSearch`.
19+
Plone frontend using Volto
20+
: A service based on React for the frontend.
21+
22+
Plone backend
23+
: The API service.
24+
25+
Postgres 14 database
26+
: Handles data persistence.
27+
28+
You can find this stack at {file}`devops/stacks/ploneconf2025-<your-github-username>.tangrama.com.br.yml`. It's modular, allowing integration of additional services, such as {term}`Varnish`, `Solr`, or `ElasticSearch`.
2229

2330
```{seealso}
2431
[Traefik Proxy with HTTPS](https://dockerswarm.rocks/traefik/)
2532
```
2633

27-
## Building Docker Images
34+
## Build Docker images
2835

29-
Ensure you build the Docker images for the Frontend and Backend servers before deployment.
36+
Ensure you build the Docker images for the frontend and backend servers before deployment.
3037
GitHub Actions, configured in {file}`.github/workflows/main.yml`, facilitate this process.
3138

3239
````{important}
@@ -56,19 +63,19 @@ Watch Usage
5663
After these commands succeed, commit all code changes, push to GitHub, and ensure all GitHub Actions successfully complete their runs.
5764
````
5865

59-
## Manual Deployment with Ansible
66+
## Manual deployment with Ansible
6067

6168
Utilize the {file}`Makefile` at {file}`devops/Makefile` for manual deployment.
6269

63-
### Deploying the Stack
70+
### Deploy the stack
6471

6572
Execute the following command from your project's {file}`devops/ansible` directory to deploy the stack defined in {file}`devops/stacks/ploneconf2025-<your-github-username>.tangrama.com.br.yml` to the remote server.
6673

6774
```shell
6875
uv run ansible-playbook playbooks/deploy.yml --tags project
6976
```
7077

71-
### Verifying Stack Status
78+
### Verify stack status
7279

7380
To check the status of all services in your stack, access the remote server:
7481

@@ -82,74 +89,90 @@ And then run the command:
8289
docker stack ps ploneconf2025-<your-github-username>-tangrama-com-br
8390
```
8491

85-
### Creating Plone Site
92+
### Create Plone site
8693

8794
On the initial deployment, the frontend containers might be unhealthy due to the unconfigured Plone site on the backend. Create a new site with:
8895

8996
```shell
9097
docker exec $(docker ps -qf 'name=_backend'|head -n1) ./docker-entrypoint.sh create-site
9198
```
9299

93-
### Monitoring Logs
100+
### Monitor logs
94101

95102
Monitor the logs of each service with these commands:
96103

97-
- Traefik: `docker service logs traefik_traefik --follow`
98-
- Frontend: `docker service logs <stack-name>_frontend --follow`
99-
- Backend: `ocker service logs <stack-name>_backend --follow`
100-
- Database: `ocker service logs <stack-name>_db --follow`
104+
```{code-block} shell
105+
:caption: Traefik
101106
102-
## Automating Deployment with GitHub Actions
107+
docker service logs traefik_traefik --follow`
108+
```
103109

104-
{term}`cookieplone` includes a GitHub Actions Workflow, located at {file}`.github/workflows/manual_deploy.yml`, enabling deployment directly from the GitHub UI.
110+
```{code-block} shell
111+
:caption: frontend
105112
106-
### Repository Configuration
113+
docker service logs <stack-name>_frontend --follow`
114+
```
107115

108-
#### Creating a New Environment
116+
```{code-block} shell
117+
:caption: backend
109118
110-
```{important}
111-
If you can't see the {guilabel}`Environment` option on the left in the {guilabel}`Settings` of your GitHub repository, you may have a private repository in a free account.
112-
You must either have a public repository or a [GitHub Team plan](https://github.com/pricing#compare-features) or a [GitHub Pro plan](https://docs.github.com/en/get-started/learning-about-github/githubs-plans) for a private repository.
113-
If you use a free additional organization under control of a paid GitHub account, the {guilabel}`Environment` will also not be visible.
119+
docker service logs <stack-name>_backend --follow`
114120
```
115121

116-
1. Log in to [GitHub](https://github.com/).
117-
2. Navigate to the project repository.
118-
3. Click `Settings`.
119-
4. Select `Environments`, then `New environment`.
120-
5. Name it after the public URL of the deployment server and configure the environment.
122+
```{code-block} shell
123+
:caption: database
121124
122-
```{seealso}
123-
In the generated project's file {file}`devops/README-GHA.md`, you can find the exact values to use for your project when completing the {guilabel}`New environment` form.
125+
docker service logs <stack-name>_db --follow`
124126
```
125127

126-
#### Adding Environment Secrets
128+
## Automate deployment with GitHub Actions
127129

128-
Add secrets in the `Secrets` section of your environment. Refer to the table below:
130+
This section describes how to configure your GitHub repository to automatically deploy your project.
129131

130-
| Secret Name | Secret Value | Description |
131-
|-------------|----------------------------------------------------------|-----------------------------------------------------------|
132-
| DEPLOY_HOST | Your hostname or IP | The Docker Swarm manager's address. |
133-
| DEPLOY_PORT | 22 | The SSHD port. |
134-
| DEPLOY_USER | Your username | A user with Docker command permissions. |
135-
| DEPLOY_SSH | Content of {file}`devops/etc/keys/plone_prod_deploy_rsa` | The private SSH key for connection. |
136-
| ENV_FILE | Content of {file}`devops/.env_file_gha` | File containing environment variables for the stack file. |
132+
{term}`Cookieplone` includes a GitHub Actions workflow, located at {file}`.github/workflows/manual_deploy.yml`, enabling deployment directly from the GitHub UI.
137133

134+
First, create a new environment.
138135

139-
## Initiating Manual Deployment
136+
1. Log in to [GitHub](https://github.com/).
137+
1. Navigate to the project repository.
138+
1. Click `Settings`.
139+
1. Select `Environments`, then `New environment`.
140140

141-
Ensure both Backend and Frontend tests are successful and images for both servers are available.
141+
```{important}
142+
If you can't see the {guilabel}`Environment` option on the left in the {guilabel}`Settings` of your GitHub repository, you may have a private repository in a free account.
143+
You must either have a public repository or a [GitHub Team plan](https://github.com/pricing#compare-features) or a [GitHub Pro plan](https://docs.github.com/en/get-started/learning-about-github/githubs-plans) for a private repository.
144+
If you use a free additional organization under control of a paid GitHub account, the {guilabel}`Environment` will also not be visible.
145+
```
142146
143-
1. Go to the project's repository on GitHub.
144-
2. Click the {guilabel}`Actions` tab.
145-
3. Find {guilabel}`Manual Deployment...` and click {guilabel}`Run workflow`.
146-
4. Select {guilabel}`Branch: main` under {guilabel}`Use workflow from`.
147-
5. Press {guilabel}`Run workflow`.
147+
1. Name the new environment after the public URL of the deployment server and configure the environment secrets.
148+
1. Add each secret in the `Secrets` section of your environment, using the values in the generated project's file {file}`devops/README-GHA.md`.
149+
150+
| Secret Name | Secret Value | Description |
151+
|---|---|---|
152+
| `DEPLOY_HOST` | Your hostname or IP | The Docker Swarm manager's address. |
153+
| `DEPLOY_PORT` | `22` | The SSHD port. |
154+
| `DEPLOY_USER` | `plone` by default, unless overridden. See {file}`devops/README-GHA.md` for actual value. | A user with Docker command permissions. |
155+
| `DEPLOY_SSH` | Content of {file}`devops/etc/keys/plone_prod_deploy_ed25519` | The private SSH key for the connection. |
156+
| `ENV_FILE` | Content of {file}`devops/.env_gha` | File containing environment variables for the stack file. |
157+
158+
159+
## Initiate manual deployment
160+
161+
Ensure both backend and frontend tests are successful, and images for both servers are available.
162+
163+
1. Go to the project's repository on GitHub.
164+
1. Click the {guilabel}`Actions` tab.
165+
1. Find {guilabel}`Manual Deployment of ploneconf2025-<your-github-username>.tangrama.com.br.yml` and click {guilabel}`Run workflow`.
166+
1. For {guilabel}`Use workflow from`, select {guilabel}`Branch: main`.
167+
1. Click {guilabel}`Run workflow`.
148168
149169
The workflow connects to `DEPLOY_HOST` using `DEPLOY_USER` and `DEPLOY_SSH` key, initiates a new deployment using the specified stack, and provides a detailed deployment report.
150170
151-
## Accessing the Site
171+
## Access the site
152172
153173
Your site should now be accessible via the defined public URL.
154174
155-
Note: Ensure you replace placeholders, such as `<url>`, with actual values per your project's specifics. Also, ensure that the paths to files and directories are correct and exist in your project structure.
175+
```{note}
176+
Ensure you replace placeholders, such as `<url>`, with actual values per your project's specifics.
177+
Also, ensure that the paths to files and directories are correct and exist in your project structure.
178+
```

0 commit comments

Comments
 (0)