Simplify the introductory container installation docs #1456
Conversation
It's a best practice to run Volto in seamless mode, where the API is served at the same domain with the /++api++ prefix. This avoids complications with browser cross-origin restrictions when the browser accesses the backend directly at a different domain. So, we should show this best practice here. The current example sets RAZZLE_API_PATH, because the default is http://localhost:8080/Plone which does not work inside a container. But, setting RAZZLE_API_PATH also stops using the best practice of seamless mode. We can avoid this by setting RAZZLE_DEV_PROXY_API_PATH instead. (Future improvement: make Volto recognize when it is running in a container, so that it can use http://host.docker.internal:8080/Plone as the default API path instead of localhost. Then it would not be necessary to set RAZZLE_DEV_PROXY_API_PATH here.)
✅ Deploy Preview for 6-docs-plone-org ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
There was a problem hiding this comment.
I have not been following environment variables, so I am not qualified to review this PR. Someone else should review and approve.
However, would you please check other instances of RAZZLE_API_PATH in both these and the Volto docs, to ensure that removing it here will not affect its presence in other places? Make sure to check all files, including Makefiles.
|
Hmm. I started checking the rest of the docs, but I'm getting myself confused. I think https://github.com/plone/documentation/blob/6-dev/docs/install/containers/images/frontend.md also needs to be updated to mention RAZZLE_DEV_PROXY_API_PATH. But here's my confusion: The dev proxy is clearly working when using the plone-frontend image, which I understand is running Volto in production mode. That matches what it says in https://6.docs.plone.org/volto/configuration/internalproxy.html ("You could also use the internal proxy for production setups. For convenience and for testing/demoing using the stock build, it is also enabled in production mode since Volto 14.") But I also see code in Volto that is clearly only using I can follow up and update the docs about this in more places but first I need to understand better myself. |
|
Answering my own question: the dev proxy is indeed always enabled. There are a couple places where things are done differently when |
|
I need to stop for today, but I'll come back to this and make some more updates. I got sidetracked working on plone/volto#4434 |
|
Indeed, I would not take the Volto docs as being 100% accurate. When we imported them initially into the main docs, they were not curated or reviewed for accuracy. The Volto docs evolved over time, and some things were not updated, but just buried beneath new stuff that was current. Just like Plone 5 docs. |
|
@stevepiercy Sure, that's my general expectation, and I'm trying to help review them now. The bit I pointed out above is in fact accurate -- I thought I saw something in the code that contradicted the docs, but I was mistaken. |
| ``` | ||
|
|
||
| Now start the Plone Frontend, linking it to the `plone6-backend`: | ||
|
|
||
| ```shell | ||
| docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_API_PATH=http://localhost:8080/Plone -e RAZZLE_INTERNAL_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest | ||
| docker run --name plone6-frontend --link plone6-backend:backend -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone -d -p 3000:3000 plone/plone-frontend:latest |
There was a problem hiding this comment.
Feedback from Wayne Glover in https://community.plone.org/t/trying-to-install-plone-6-on-windows-gets-me-half-way/16084/16:
please consider adding a line above this something to the effect: "The docker run code below is based on the name of the site being "Plone". If you named your site something different, please revise the code below by changing the name"
|
Is this documentation update something that can be moved forward with the recent fixes to seamless mode and the dev proxy path variables in Volto 16.18.0? (https://plone.org/news-and-events/news/2023/plone-6-0-3-released) |
|
@davisagli would you please nudge this PR onward? |
|
@stevepiercy I'll be honest, I've been procrastinating on this because I discovered that the "install from containers" section has some subsections that have useful information but don't belong in their current location. I think a lot of it probably should move into the deployment section. Anyway this is just excuses but that's why I haven't gotten to what might at first glance look like a small fix. |
|
Look at it this way, you can't make the Deployment section any worse than it is now. 🤡 Do you want to chat and figure out where bits should go? |
|
@stevepiercy Yes, but I'm out of time for today. Sometime this next week? |
|
Yup, hit me up on Discord. |
|
@davisagli poke. |
|
@davisagli what's the status of this PR? What's the relation to #1652? |
It's a best practice to run Volto in seamless mode, where the API is served at the same domain with the /++api++ prefix. This avoids complications with browser cross-origin restrictions when the browser accesses the backend directly at a different domain.
So, we should show this best practice here. The current example sets RAZZLE_API_PATH, because the default is http://localhost:8080/Plone which does not work inside a container. But, setting RAZZLE_API_PATH also stops using the best practice of seamless mode. We can avoid this by setting RAZZLE_DEV_PROXY_API_PATH instead.
(Future improvement: make Volto recognize when it is running in a container, so that it can use http://host.docker.internal:8080/Plone as the default API path instead of localhost. Then it would not be necessary to set RAZZLE_DEV_PROXY_API_PATH here.)