Containers simple install instructions prevent Volto frontend access from remote hosts

[kenmanheimer]

Plone Documentation versions affected

• [ ] 5.x
• [X] 6.x

Description

In the current version of https://github.com/plone/documentation/blob/6-dev/docs/install/containers/index.md the command for starting the Volto frontend results in a frontend that malfunctions mysteriously for visits by browsers not running on the same host as the containers.

Specifically, RAZZLE_API_PATH=http://localhost:8080/Plone causes Volto code running in the browser to do API calls to the Plone backend running on localhost:8080, which is incorrect. The correct value would include the fully qualified domain name of the container host, which in many cases can be expressed as RAZZLE_API_PATH=http://$HOSTNAME:8080/Plone.

To provide for cases where the hostname on the container host is not properly configured with the fully qualified domain name, it would be helpful to include a bit of explanation suggesting checking that echo $HOSTNAME yields the fully qualified domain name, and if not then substitute for $HOSTNAME in the frontend start command.

For background on this issue, see my forum posting describing the problem and the specific and related measures that solved the problem: https://community.plone.org/t/need-help-solving-weird-plone-6-volto-frontend-problem/15829/7

[stevepiercy]

The install container docs assume that everything will be done locally, and not as a deployment where the site would be remote to the client browser. Did you assume it would be a deployment to a remote machine? If so, we need to be more clear.

Our container deployment story does not exist, except in the training, and even then I am having troubles with the training.

[kenmanheimer]

It seems to me that the setting change I am suggesting:

1. May be essential for a container deployment story to be developed
2. Would not be detrimental to the current development process
3. Would remove a perplexing roadblock to developers who use a server host that is remote to their development workstation
4. Might reduce the troubles you mention in developing your training. (At the least it would reduce the need for such developers to establish tunnels for ports 3000, 8080, and maybe others.)

I can see wanting to assess whether the change I am suggesting would incur performance or security costs. I do not understand dismissing the proposal simply because it eliminates a deployment obstacle when the deployment story does not yet exist.

[stevepiercy]

I do not dismiss your proposal. I think it belongs in Deployment, or perhaps a new section Development, not Install. Install is intended as the happy path, without the complexities of remote services.

We need content for Container Deployment in the Plone 6 Docs. I had trouble with the Deployment training, meaning I had trouble getting it to work as written, otherwise its content would already be that part of Plone 6 Docs. I happen to be working on resolving my issues with it during the holiday. I think that is where your proposal would go. In fact, why not make your proposal there, incorporating it there now, allowing it to be brought over into Plone 6 Docs?

[kenmanheimer]

I am not sure what you mean by making my proposal in the Container Deployment part of the Plone 6 Docs, but would be happy to consider doing so if you say more about what specifically that means.

I believe there's a more important concern to raise here, however: making it easy for people evaluating the system to find traction. I think the very specific issue of the setting change I am proposing relates to the larger issue.

The specific setting, unchanged, presents an obstacle to people trying to do reasonable stuff with the elementary containers build. I first wanted to access the site from a browser that is remote from the server host, and then wanted to evaluate running the trial site behind TLS. Using $HOSTNAME instead of localhost enables that. There may be a specific reason to not make this change, but if there isn't I think it would be good to remove the blocker and switch over. I can understand if there's not collective bandwidth to evaluate the question, but then it would be good to preserve the question for evaluation when there is the opportunity.

I think the kind of work you're doing with the trainings helps address the larger issue, of helping people new to the system find traction with it. Along those lines, after I spent a lot of time finding pathways to do the things I needed to do I wrote a substantial account of what I found, in the hopes that it would help others similarly trying to find their way: (Building and operating a site using the Volto Plone 6 frontend with addons and customizations deployed behind TLS - Development / Plone 6 UI (Volto) - Plone Community)[https://community.plone.org/t/building-and-operating-a-site-using-the-volto-plone-6-frontend-with-addons-and-customizations-deployed-behind-tls/16048]. Maybe something in it will be useful for the training you're writing.

[stevepiercy]

making it easy for people evaluating the system to find traction.

We collectively are trying to solve that larger issue. PRs are welcome, as are discussions about how to proceed.

I first wanted to access the site from a browser that is remote from the server host, and then wanted to evaluate running the trial site behind TLS.

I picture your browser on your laptop accessing a Plone site that is deployed on a remote server, such as on the cloud. Is that what you mean? I have a hard time understanding the stack or network topology you describe.

Building and operating a site using the Volto Plone 6 frontend with addons and customizations deployed behind TLS

I have that open while running through the Plone Deployment training for the third time, just in case I find a nugget of wisdom (setting up TLS is the most important task, IMO). I found a few bugs in the training, which I corrected in several PRs. I found more bugs yesterday and started preparing it for migration into the Plone 6 Docs in https://github.com/plone/training/pull/702. My goal is to migrate content from that training into the Plone 6 Docs this week. If you have any suggestions for improving that training based on your experience, now is the time to make a PR, so I can include it in the migration to Plone 6 Docs.

[kenmanheimer]

making it easy for people evaluating the system to find traction.

We collectively are trying to solve that larger issue. PRs are welcome, as are discussions about how to proceed.

I first wanted to access the site from a browser that is remote from the server host, and then wanted to evaluate running the trial site behind TLS.

I picture your browser on your laptop accessing a Plone site that is deployed on a remote server, such as on the cloud. Is that what you mean? I have a hard time understanding the stack or network topology you describe.

Yes, I have a headless host in the cloud where I run the services, and operate and access it from laptops to configure, operate and interact with the services.

Building and operating a site using the Volto Plone 6 frontend with addons and customizations deployed behind TLS

I have that open while running through the Plone Deployment training for the third time, just in case I find a nugget of wisdom (setting up TLS is the most important task, IMO). I found a few bugs in the training, which I corrected in several PRs. I found more bugs yesterday and started preparing it for migration into the Plone 6 Docs in plone/training#702. My goal is to migrate content from that training into the Plone 6 Docs this week. If you have any suggestions for improving that training based on your experience, now is the time to make a PR, so I can include it in the migration to Plone 6 Docs.

Much or all of what I can suggest regarding TLS is conveyed by the docker-compose.yml and default.conf file that I included comment 6 of a thread that I referenced in my document. Things to note:

• I use a docker-compose.yml volume to mount /etc/letsencrypt on my server host into the nginx container. That way I can use LetsEncrypt to install certs on my server host and have them available in the right places in the container. default.conf is configured accordingly.
• Of course, I found what I am suggesting in this issue about using $HOSTNAME rather than localhost in this issue necessary.

I'm preparing for travel so will have limited time this week, but will see if there's anything I can do before I depart. I hope what I've written already will be helpful.