Deploy the project#
Project stack#
This guide outlines the steps to deploy the project using a Docker stack comprising:
- Traefik
A router and TLS termination tool, integrated with Let's Encrypt for complimentary secure certificates.
- 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 devops/stacks/ploneconf2025-<your-github-username>.tangrama.com.br.yml
. It's modular, allowing integration of additional services, such as Varnish, Solr
, or ElasticSearch
.
See also
Build Docker images#
Ensure you build the Docker images for the frontend and backend servers before deployment.
GitHub Actions, configured in .github/workflows/main.yml
, facilitate this process.
Important
Before deploying, run the following commands from your project's root directory to format the code and run tests.
make check
make test
The output from make test
may vary according to changes in code.
The following console output indicates that no tests were run, and prompts you to choose an action.
No tests found related to files changed since last commit.
Press `a` to run all tests, or run Jest with `--watchAll`.
Watch Usage
› Press a to run all tests.
› Press f to run only failed tests.
› Press p to filter by a filename regex pattern.
› Press t to filter by a test name regex pattern.
› Press q to quit watch mode.
› Press Enter to trigger a test run.
After these commands succeed, commit all code changes, push to GitHub, and ensure all GitHub Actions successfully complete their runs.
Manual deployment with Ansible#
Utilize the Makefile
at devops/Makefile
for manual deployment.
Deploy the stack#
Execute the following command from your project's devops/ansible
directory to deploy the stack defined in devops/stacks/ploneconf2025-<your-github-username>.tangrama.com.br.yml
to the remote server.
uv run ansible-playbook playbooks/deploy.yml --tags project
Verify stack status#
To check the status of all services in your stack, access the remote server:
ssh root@ploneconf2025-<your-github-username>.tangrama.com.br
And then run the command:
docker stack ps ploneconf2025-<your-github-username>-tangrama-com-br
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:
docker exec $(docker ps -qf 'name=_backend'|head -n1) ./docker-entrypoint.sh create-site
Monitor logs#
Monitor the logs of each service with these commands:
docker service logs traefik_traefik --follow`
docker service logs <stack-name>_frontend --follow`
docker service logs <stack-name>_backend --follow`
docker service logs <stack-name>_db --follow`
Automate deployment with GitHub Actions#
This section describes how to configure your GitHub repository to automatically deploy your project.
Cookieplone includes a GitHub Actions workflow, located at .github/workflows/manual_deploy.yml
, enabling deployment directly from the GitHub UI.
First, create a new environment.
Log in to GitHub.
Navigate to the project repository.
Click
Settings
.Select
Environments
, thenNew environment
.Important
If you can't see the Environment option on the left in the 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 or a GitHub Pro plan for a private repository. If you use a free additional organization under control of a paid GitHub account, the Environment will also not be visible.
Name the new environment after the public URL of the deployment server and configure the environment secrets.
Add each secret in the
Secrets
section of your environment, using the values in the generated project's filedevops/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. Seedevops/README-GHA.md
for actual value.A user with Docker command permissions.
DEPLOY_SSH
Content of
devops/etc/keys/plone_prod_deploy_ed25519
The private SSH key for the connection.
ENV_FILE
Content of
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.
Go to the project's repository on GitHub.
Click the Actions tab.
Find Manual Deployment of ploneconf2025-<your-github-username>.tangrama.com.br.yml and click Run workflow.
For Use workflow from, select Branch: main.
Click 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.
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.