Skip to content

Commit

Permalink
Merge pull request #886 from plone/installing-2024
Browse files Browse the repository at this point in the history
Update training to Plone Conference 2024
  • Loading branch information
ericof authored Nov 25, 2024
2 parents 995caeb + e7d4eca commit 11fedad
Show file tree
Hide file tree
Showing 12 changed files with 164 additions and 161 deletions.
8 changes: 4 additions & 4 deletions docs/effective-volto/getting-started/project.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,13 @@ In two separate terminal sessions, start backend and frontend:
To start backend:

```shell
make start-backend
make backend-start
```

To start frontend:

```shell
make start-frontend
make frontend-start
```

You can stop each one with {kbd}`ctrl-c`.
Expand All @@ -78,11 +78,11 @@ make build
and restart backend and frontend by stopping and re-running

```shell
make start-backend
make backend-start
```

```shell
make start-frontend
make frontend-start
```

## Project Generation Options
Expand Down
8 changes: 7 additions & 1 deletion docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Dexterity
[Dexterity](https://github.com/plone/plone.dexterity), the base framework for building content types, both through-the-web and as filesystem code for Zope.
Dublin Core
The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, and other online content).
The Dublin Core Schema is a small set of vocabulary terms that can be used to describe web resources (video, images, web pages, and other online content).
It can also be used to describe physical resources such as books or CDs, and objects like artworks.
ZMI
Expand Down Expand Up @@ -290,6 +290,12 @@ cookiecutter-plone-starter
[cookiecutter-plone-starter](https://github.com/collective/cookiecutter-plone-starter) is a `cookiecutter` template, created by the Plone community, to bootstrap
a new Plone 6 project using Volto and a relational database.

Cookiecutter
[Cookiecutter](https://github.com/cookiecutter/cookiecutter) is tool used to generate codebases / projects.

cookieplone
[cookieplone](https://github.com/plone/cookieplone) is a wrapper around {term}`Cookiecutter` designed to streamline the development of Plone codebases

Traefik
[Traefik](https://doc.traefik.io/traefik/) is an open-source reverse proxy and load balancer designed to handle HTTP and TCP applications.
It simplifies the deployment and routing of services and is particularly well-suited for cloud-native and containerized environments,
Expand Down
Binary file added docs/plone-deployment/_static/request_flow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 4 additions & 5 deletions docs/plone-deployment/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This guide outlines the steps to deploy the project using a Docker stack compris
- **Plone Backend:** The API service.
- **Postgres 14 Database:** Handles data persistence.

You can find this stack at {file}`devops/stacks/<url>.yml`. It's modular, allowing easy integration of additional services like {term}`Varnish`, `Solr`, or `ElasticSearch`.
You can find this stack at {file}`devops/stacks/ploneconf2024-<your-github-username>.tangrama.com.br.yml`. It's modular, allowing easy integration of additional services like {term}`Varnish`, `Solr`, or `ElasticSearch`.

## Building Docker Images

Expand All @@ -28,8 +28,7 @@ Ensure you build the Docker images for the Frontend and Backend servers before d
Before deploying, push all code changes and ensure GitHub Actions successfully complete their runs. Execute these commands to format the code and run tests:
```shell
make format
make i18n
make check
make test
```
````
Expand All @@ -41,7 +40,7 @@ Utilize the `Makefile` at {file}`devops/Makefile` for manual deployment.

### Deploying the Stack

Execute the following command to deploy the stack defined in {file}`devops/stacks/<url>.yml` to the remote server:
Execute the following command to deploy the stack defined in {file}`devops/stacks/ploneconf2024-<your-github-username>.tangrama.com.br.yml` to the remote server:

```shell
make stack-deploy
Expand Down Expand Up @@ -73,7 +72,7 @@ Monitor the logs of each service with these commands:

## Automating Deployment with GitHub Actions

{term}`cookiecutter-plone-starter` includes a GitHub Actions Workflow, located at {file}`.github/workflows/manual_deploy.yml`, enabling deployment directly from the GitHub UI.
{term}`cookieplone` includes a GitHub Actions Workflow, located at {file}`.github/workflows/manual_deploy.yml`, enabling deployment directly from the GitHub UI.

### Repository Configuration

Expand Down
98 changes: 36 additions & 62 deletions docs/plone-deployment/plone-docker-images.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,68 +22,37 @@ like the one below:

```Dockerfile
# syntax=docker/dockerfile:1
FROM node:18-slim as base
FROM base as builder
ARG VOLTO_VERSION
FROM plone/frontend-builder:${VOLTO_VERSION} AS builder

RUN <<EOT
set -e
apt update
apt install -y --no-install-recommends python3 build-essential
mkdir /app
chown -R node:node /app
rm -rf /var/lib/apt/lists/*
EOT
COPY --chown=node packages/volto-project-title /app/packages/volto-project-title
COPY --chown=node volto.config.js /app/
COPY --chown=node package.json /app/package.json.temp

COPY --chown=node . /build/
RUN corepack enable

USER node
WORKDIR /build
RUN <<EOT
RUN --mount=type=cache,id=pnpm,target=/app/.pnpm-store,uid=1000 <<EOT
set -e
make install
yarn build
python3 -c "import json; orig_data = json.load(open('package.json.temp')); orig_deps = orig_data['dependencies']; data = json.load(open('package.json')); data['dependencies'].update(orig_deps); json.dump(data, open('package.json', 'w'), indent=2)"
rm package.json.temp
pnpm install && pnpm build:deps
pnpm build
pnpm install --prod
EOT

FROM base
FROM plone/frontend-prod-config:${VOLTO_VERSION}

LABEL maintainer="Plone Community <collective@plone.org>" \
org.label-schema.name="ploneconf2023-training-frontend" \
org.label-schema.description="Plone Conference Training Frontend." \
LABEL maintainer="Plone Community <dev@plone.org>" \
org.label-schema.name="project-title-frontend" \
org.label-schema.description="Project Title frontend image." \
org.label-schema.vendor="Plone Community"

# Install busybox and wget
COPY --from=builder /app/ /app/

RUN <<EOT
set -e
apt update
apt install -y --no-install-recommends busybox wget
busybox --install -s
rm -rf /var/lib/apt/lists/*
mkdir /app
chown -R node:node /app
corepack enable pnpm
corepack use [email protected]
corepack prepare [email protected] --activate
EOT

# Run the image with user node
USER node

# Copy -
COPY --from=builder /build/ /app/

# Set working directory to /app
WORKDIR /app

# Expose default Express port
EXPOSE 3000

# Set healthcheck to port 3000
HEALTHCHECK --interval=10s --timeout=5s --start-period=30s CMD [ -n "$LISTEN_PORT" ] || LISTEN_PORT=3000 ; wget -q http://127.0.0.1:"$LISTEN_PORT" -O - || exit 1

# Entrypoint would be yarn
ENTRYPOINT [ "yarn" ]

# And the image will run in production mode
CMD ["start:prod"]

```

## plone/plone-backend
Expand All @@ -97,34 +66,39 @@ One example of such extension would be:

```Dockerfile
# syntax=docker/dockerfile:1
ARG PLONE_VERSION=6.0.7
FROM plone/server-builder:${PLONE_VERSION} as builder
ARG PLONE_VERSION=6.0.13
FROM plone/server-builder:${PLONE_VERSION} AS builder

WORKDIR /app


# Add local code
COPY . .
COPY scripts/ scripts/
COPY . src

# Install local requirements and pre-compile mo files
RUN <<EOT
set -e
bin/pip install mxdev
mv requirements-docker.txt requirements.txt
sed -i 's/-e src\/ploneconf2023_training\[test\]/src\/ploneconf2023_training/g' mx.ini
bin/mxdev -c mx.ini
bin/pip install -r requirements-mxdev.txt
bin/python /compile_mo.py
bin/pip install mxdev uv
sed -i 's/-e .\[test\]/./g' src/mx.ini
cd /app/src
# remove potentially existing virtualenv from local build
rm -rf .venv
../bin/mxdev -c mx.ini
../bin/uv pip install -r requirements-mxdev.txt
../bin/python /compile_mo.py
cd /app
rm -Rf src/
EOT

FROM plone/server-prod-config:${PLONE_VERSION}

LABEL maintainer="Plone Community <[email protected]>" \
org.label-schema.name="ploneconf2023-training-backend" \
org.label-schema.name="ploneconf2024-training-backend" \
org.label-schema.description="Plone Conference Training Backend." \
org.label-schema.vendor="Plone Community"

# Copy /app from builder -
# Copy /app from builder
COPY --from=builder /app /app

RUN <<EOT
Expand Down
6 changes: 6 additions & 0 deletions docs/plone-deployment/plone-stack.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,12 @@ Webserver → Web Accelerator → Plone Frontend → Plone Backend → Database

In a multi-server environment, load distribution and redundancy are achieved through various configurations, enabling horizontal scaling.

```{figure} _static/request_flow.png
:alt: Flow of a request to https://example.com
Flow of a request to https://example.com
```

#### Webserver and Web Accelerator Layer

Externally accessible machine hosting both the webserver and web accelerator on ports 80 and 443.
Expand Down
62 changes: 47 additions & 15 deletions docs/plone-deployment/project-edit.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ Both Plone Frontend and Backend in your project support add-on integration. Add-

### Adding a New Block to the Frontend

We’ll illustrate the process of integrating a Frontend add-on, `@plonegovbr/volto-code-block`, which renders highlighted source code blocks. We’ll centralize all modifications within our project's add-on, `volto-ploneconf2023`, to streamline future Volto version upgrades.
We’ll illustrate the process of integrating a Frontend add-on, `@plonegovbr/volto-code-block`, which renders highlighted source code blocks. We’ll centralize all modifications within our project's add-on, `volto-ploneconf2024`, to streamline future Volto version upgrades.

#### Incorporating a New Dependency

Edit {file}`frontend/src/addons/volto-ploneconf2023/package.json` and append `@plonegovbr/volto-code-block` to the `addons` and `dependencies` sections, as shown below:
Edit {file}`frontend/packages/volto-ploneconf2024/package.json` and append `@plonegovbr/volto-code-block` to the `addons` and `dependencies` sections, as shown below:

```json
"addons": [
Expand All @@ -39,20 +39,20 @@ Edit {file}`frontend/src/addons/volto-ploneconf2023/package.json` and append `@p

#### Reinstalling the Project

Execute `make install-frontend` from the repository root to install the new add-on and update {file}`frontend/yarn.lock`.
Execute `make frontend-install` from the repository root to install the new add-on and update {file}`frontend/pnpm-lock.yaml`.

#### Restarting the Project

Start your project with `make start-backend` and `make start-frontend` in different shells.
Start your project with `make backend-start` and `make frontend-start` in different shells.
Navigate to http://localhost:3000.
After authentication, the new block becomes available on the content edit page.

#### Committing Changes

Format your codebase with `make format`, then commit and push the changes:
Format your codebase with `make check`, then commit and push the changes:

```shell
git add frontend/src/addons/volto-ploneconf2023/package.json frontend/yarn.lock
git add frontend/packages/volto-ploneconf2024/package.json frontend/pnpm-lock.yaml
git commit -m "Add @plonegovbr/volto-code-block"
git push
```
Expand All @@ -66,21 +66,53 @@ We’ll now add GitHub OAuth authentication, involving both Backend and Frontend
Follow GitHub's guide on [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app), using the following configurations:

- **Application Name**: `plone-conference-local`
- **Homepage URL**: `http://ploneconf2023.localhost`
- **Application Description**: `Plone Conference 2023`
- **Authorization Callback URL**: `http://ploneconf2023.localhost/login-authomatic/github`
- **Homepage URL**: `http://ploneconf2024.localhost`
- **Application Description**: `Plone Conference 2024`
- **Authorization Callback URL**: `http://ploneconf2024.localhost/`

### Backend: Installing `pas.plugins.authomatic`

Modify `backend/src/ploneconf2023/setup.py` to include `pas.plugins.authomatic` in `install_requires`. Also, update `backend/src/ploneconf2023/src/ploneconf2023/dependencies.zcml` to load the package configuration during Plone Backend startup.
Modify `backend/setup.py` to include `pas.plugins.authomatic` in `install_requires`. Also, update `backend/src/ploneconf2024/dependencies.zcml` to load the package configuration during Plone Backend startup.

### Frontend: Installing `volto-authomatic`

Add `@plone-collective/volto-authomatic` to the `addons` and `dependencies` sections of `frontend/src/addons/volto-ploneconf2023/package.json`. Run `make install-frontend` to update the dependencies.
Add `@plone-collective/volto-authomatic` to the `addons` and `dependencies` sections of `frontend/packages/volto-ploneconf2024/package.json`. Run `make frontend-install` to update the dependencies.

### Activating and Configuring the Add-on

Start the Docker Compose stack with `make stack-start`. Navigate to [http://ploneconf2023.localhost/ClassicUI/login](http://ploneconf2023.localhost/ClassicUI/login) and authenticate.
````{note}
To ensure the name `ploneconf24.localhost` points to the address `127.0.0.1`, we need to edit the file located at:
`C:\Windows\System32\Drivers\etc\hosts`
1. Open the Start Menu and search for **Notepad**.
Right-click on it and choose **Run as administrator**.
If Windows asks if you want the application to make changes to the system, click **Yes**.
(If you don’t open Notepad as an administrator, you won’t be able to modify the `hosts` file.)
2. In Notepad, click **File » Open**.
Then navigate to the following folder:
`C:` » `Windows` » `System32` » `Drivers` » `etc`.
3. In the file dialog, change the filter from **Text Documents (*.txt)** to **All Files (*.*)**.
You should now see the `hosts` file. Select it and click **Open**.
4. At the end of the file, add the following line:
```
127.0.0.1 ploneconf24.localhost
```
5. Save the file.
6. Open PowerShell and confirm that the name resolution is working correctly by typing:
```shell
ping ploneconf24.localhost
```
````

Start the Docker Compose stack with `make stack-start`. Navigate to [http://ploneconf2024.localhost/ClassicUI/login](http://ploneconf2024.localhost/ClassicUI/login) and authenticate.

Install `pas.plugins.authomatic` from the {guilabel}`Add-ons` control panel and configure it with the following JSON configuration, replacing `KEYHERE` and `SECRETHERE` with your GitHub OAuth application’s client ID and secret.

Expand Down Expand Up @@ -114,7 +146,7 @@ Install `pas.plugins.authomatic` from the {guilabel}`Add-ons` control panel and

### Authenticating with GitHub

Visit [http://ploneconf2023.localhost/login](http://ploneconf2023.localhost/login) and log in using GitHub.
Visit [http://ploneconf2024.localhost/login](http://ploneconf2024.localhost/login) and log in using GitHub.

### Configure the OAuth user permissions

Expand All @@ -126,7 +158,7 @@ For the purpose of this training, check {guilabel}`Manager`, then click {guilabe

```{warning}
If you need to authenticate bypassing OAuth, there are fallback login forms:
* Backend: Available at [http://ploneconf2023.localhost/ClassicUI/failsafe_login](http://ploneconf2023.localhost/ClassicUI/failsafe_login).
* Frontend: Available at [http://ploneconf2023.localhost/fallback_login](http://ploneconf2023.localhost/fallback_login).
* Backend: Available at [http://ploneconf2024.localhost/ClassicUI/failsafe_login](http://ploneconf2024.localhost/ClassicUI/failsafe_login).
* Frontend: Available at [http://ploneconf2024.localhost/fallback_login](http://ploneconf2024.localhost/fallback_login).
```
Loading

0 comments on commit 11fedad

Please sign in to comment.