Skip to content

Final polish of Deployment docs #985

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericof merged 2 commits into from
Oct 21, 2025
Merged

Final polish of Deployment docs #985

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db72081
Final polish of Deployment docs
stevepiercy Oct 15, 2025
9f79e04
Merge branch 'main' into deployment-polish-3
stevepiercy Oct 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 78 additions & 55 deletions docs/plone-deployment/deploy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,39 @@
---
myst:
html_meta:
"description": "Learn how to deploy Plone using make, GitHub Actions, or Gitlab CI with ease."
"property=og:description": "A comprehensive guide to deploying Plone via various methods."
"property=og:title": "Efficiently Deploy Plone: A Step-by-Step Guide"
"keywords": "Deploy, Plone, Makefile, GitHub Actions, Gitlab CI"
"description": "How to deploy a Plone project using make, GitHub Actions, or Gitlab CI"
"property=og:description": "How to deploy a Plone project using make, GitHub Actions, or Gitlab CI"
"property=og:title": "How to deploy a Plone project using make, GitHub Actions, or Gitlab CI"
"keywords": "deploy, Plone, Makefile, GitHub Actions, GitLab CI"
---

# Deploying the Project
# Deploy the project

## Project Stack
## Project stack

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

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

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`.
Plone frontend using Volto
: A service based on React for the frontend.

Plone backend
: The API service.

Postgres 14 database
: Handles data persistence.

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

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

## Building Docker Images
## Build Docker images

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

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

## Manual Deployment with Ansible
## Manual deployment with Ansible

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

### Deploying the Stack
### Deploy the stack

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.

```shell
uv run ansible-playbook playbooks/deploy.yml --tags project
```

### Verifying Stack Status
### Verify stack status

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

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

### Creating Plone Site
### Create Plone site

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

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

### Monitoring Logs
### Monitor logs

Monitor the logs of each service with these commands:

- Traefik: `docker service logs traefik_traefik --follow`
- Frontend: `docker service logs <stack-name>_frontend --follow`
- Backend: `ocker service logs <stack-name>_backend --follow`
- Database: `ocker service logs <stack-name>_db --follow`
```{code-block} shell
:caption: Traefik

## Automating Deployment with GitHub Actions
docker service logs traefik_traefik --follow`
```

{term}`cookieplone` includes a GitHub Actions Workflow, located at {file}`.github/workflows/manual_deploy.yml`, enabling deployment directly from the GitHub UI.
```{code-block} shell
:caption: frontend

### Repository Configuration
docker service logs <stack-name>_frontend --follow`
```

#### Creating a New Environment
```{code-block} shell
:caption: backend

```{important}
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.
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.
If you use a free additional organization under control of a paid GitHub account, the {guilabel}`Environment` will also not be visible.
docker service logs <stack-name>_backend --follow`
```

1. Log in to [GitHub](https://github.com/).
2. Navigate to the project repository.
3. Click `Settings`.
4. Select `Environments`, then `New environment`.
5. Name it after the public URL of the deployment server and configure the environment.
```{code-block} shell
:caption: database

```{seealso}
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.
docker service logs <stack-name>_db --follow`
```

#### Adding Environment Secrets
## Automate deployment with GitHub Actions

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

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

First, create a new environment.

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

Ensure both Backend and Frontend tests are successful and images for both servers are available.
```{important}
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.
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.
If you use a free additional organization under control of a paid GitHub account, the {guilabel}`Environment` will also not be visible.
```

1. Go to the project's repository on GitHub.
2. Click the {guilabel}`Actions` tab.
3. Find {guilabel}`Manual Deployment...` and click {guilabel}`Run workflow`.
4. Select {guilabel}`Branch: main` under {guilabel}`Use workflow from`.
5. Press {guilabel}`Run workflow`.
1. Name the new environment after the public URL of the deployment server and configure the environment secrets.
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`.

| Secret Name | Secret Value | Description |
|---|---|---|
| `DEPLOY_HOST` | Your hostname or IP | The Docker Swarm manager's address. |
| `DEPLOY_PORT` | `22` | The SSHD port. |
| `DEPLOY_USER` | `plone` by default, unless overridden. See {file}`devops/README-GHA.md` for actual value. | A user with Docker command permissions. |
| `DEPLOY_SSH` | Content of {file}`devops/etc/keys/plone_prod_deploy_ed25519` | The private SSH key for the connection. |
| `ENV_FILE` | Content of {file}`devops/.env_gha` | File containing environment variables for the stack file. |


## Initiate manual deployment

Ensure both backend and frontend tests are successful, and images for both servers are available.

1. Go to the project's repository on GitHub.
1. Click the {guilabel}`Actions` tab.
1. Find {guilabel}`Manual Deployment of ploneconf2025-<your-github-username>.tangrama.com.br.yml` and click {guilabel}`Run workflow`.
1. For {guilabel}`Use workflow from`, select {guilabel}`Branch: main`.
1. Click {guilabel}`Run workflow`.

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.

## Accessing the Site
## Access the site

Your site should now be accessible via the defined public URL.

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.
```{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.
```