Deploying the Project#
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 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.
You can find this stack at devops/stacks/ploneconf2024-<your-github-username>.tangrama.com.br.yml
. It's modular, allowing easy integration of additional services like Varnish, Solr
, or ElasticSearch
.
See also
Building Docker Images#
Ensure you build the Docker images for the Frontend and Backend servers before deployment.
GitHub Actions, configured in .github/workflows/backend.yml
and .github/workflows/frontend.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 devops/Makefile
#
Utilize the Makefile
at devops/Makefile
for manual deployment.
Deploying the Stack#
Execute the following command from your project's devops
directory to deploy the stack defined in devops/stacks/ploneconf2024-<your-github-username>.tangrama.com.br.yml
to the remote server.
make stack-deploy
Verifying Stack Status#
To check the status of all services in your stack, run:
make stack-status
Creating 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:
make stack-create-site
Monitoring Logs#
Monitor the logs of each service with these commands:
Traefik:
make stack-logs-webserver
Frontend:
make stack-logs-frontend
Backend:
make stack-logs-backend
Backend:
make stack-logs-db
Automating Deployment with GitHub Actions#
cookieplone includes a GitHub Actions Workflow, located at .github/workflows/manual_deploy.yml
, enabling deployment directly from the GitHub UI.
Repository Configuration#
Creating a New 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.
Log in to GitHub.
Navigate to the project repository.
Click
Settings
.Select
Environments
, thenNew environment
.Name it after the public URL of the deployment server and configure the environment.
See also
In the generated project's file devops/README-GHA.md
, you can find the exact values to use for your project when completing the New environment form.
Adding Environment Secrets#
Add secrets in the Secrets
section of your environment. Refer to the table below:
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 |
The private SSH key for connection. |
ENV_FILE |
Content of |
File containing environment variables for the stack file. |
Adding Repository Variables#
Navigate to Variables, add the repository variable:
. UnderName |
Value |
---|---|
LIVE_ENV |
The name of the earlier created environment |
This variable is referenced in .github/workflows/manual_deploy.yml
.
Initiating 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... and click Run workflow.
Select Branch: main under Use workflow from.
Press 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#
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.