Volto deployment, beyond basic, as a subdomain?


we are running Plone 5 with the usual, heavily customized, server side UI rendering. Nothing new :grinning_face_with_smiling_eyes:

We are however, starting to grow tools around that Plone website. We wanted to use something more interactive/powerful (as the tools have to handle a lot of data) and decided to use react for that, and what's best if we already have a package that puts both together? :smiley:

Now the tricky part :slight_smile:

I thought that we could deploy our website as usual at https://www.foo.com and have Volto deployed at https://volto.foo.com

Is that even possible? :thinking: From the docs Simple deployment - Volto Developer Documentation I'm getting a bit confused with API_PATH, RAZZLE_API_PATH together with the seamless mode, and thus if we have to pass it on the build command, or at the start command :confused:

Can anyone shed some light on this matter? Are the docs on docs.voltocms.com still the canonical ones?

1 Like

Sure, it's possible. docs.voltocms.com is canonical so far.

The seamless mode can be summarized like this: all those env vars are automatically computed from the system (Host header and such). You just have to make sure that the restapi JSON api calls go directly to the Plone backend (header inspection or simply detecting the ++api++ traverser marker from the URLs).

volto.foo.com is no different from www.foo.com, www.* is still a subdomain just like volto.* would be.

@tiberiuichim thanks! now, as a newbie deploying such things, I'm still not sure how I have to go with it :sweat_smile:

I'm doing:

RAZZLE_API_PATH=https://volto.foo.com yarn build
yarn start:prod

And I get the following output:

Volto is running in SEAMLESS mode
๐ŸŽญ Volto started at https://volto.foo.com ๐Ÿš€

Ok, now I see, it does indeed work :tada:

Now somehow, PAS does not authenticate the request coming from volto :sweat: but as we have that heavily customized, I guess is on our side :thinking:

Given that it says that seamless mode is enabled, does that mean, that we can build the project on CI and send (what?) to production, so we don't have to run yarn build on the server? :thinking:

I had to bump our testing server to 3 Gb of RAM only to compile volto :sweat_smile:

1 Like

@gforcada no need to set RAZZLE_API_PATH when you run yarn build.

@gforcada I'm interested in what did confuse you (or trick you) in the docs about seamless mode, and how do you think that they can be improved.

/cc @fredvd

As you are asking... (I noticed that now the docs are on dev-docs.plone.org... but anyway the content is the same, with the same twists that are still confusing me).

Environment variables: on Simple deployment โ€“ Frontend โ€“ Deploying โ€” Plone Documentation v6.0-dev it says:

(PORT=3000, API_PATH=http://localhost:8080/Plone).

But then uses RAZZLE_API_PATH everywhere else, so API_PATH or RAZZLE_API_PATH ? :thinking:

And then, this API_PATH is for the backend, i.e. volto connecting to Plone, but what about the frontend domain? i.e. in my example above I want to serve volto from volto.foo.com while Plone should be served from www.foo.com how do I achieve that? On this deploying/simple.html I don't see it :thinking:

Finally on that very same documentation there is an nginx snippet which is missing a closing curly brace (reported at Error on the simple deployment documentation nginx snippet ยท Issue #3157 ยท plone/volto ยท GitHub) but that example only has a location part not the server part where one, I would expect, has to define the domain one serves volto under, so is an incomplete example :confused:

Another thing, is that you run yarn build and yarn start by just reading the simple.html documentation, but after the start it says that it's running in seamless mode, so, again, I'm getting confused: is seamless always on? Then this simple documentation needs to be merged already with the seamless mode documentation, as that one is meaningless if seamless mode is always on, or otherwise we are not told how to not enable seamless mode.

I'm not saying it needs to go away or be turned off, but from the documentation point of view, it looks like that's how it should work, but the reality is different, so either the code or the documentation should adapt to the other (I guess one will want to update the docs rather than revert the code :stuck_out_tongue_closed_eyes: )

Does any of that make sense? :sweat_smile:

Indeed, the "simple" should be rewritten or removed, since seamless is the new "simple" :slight_smile: and seamless is the default, yes. I'd recommend you go for it.


a try.

The env var is RAZZLE_API_PATH everywhere.

I won't deal (at least at the beginning) with different domains. Solving CORS issues sucks. But, if you still need to do that, you'll need to open the CORS headers for that domain (so volto.foo.com will be able to access www.foo.com from a browser.)

In an ideal world,

volto.foo.com -> SSR node server (see Nginx config in seamless mode docs)
volto.foo.com/++api++ -> Plone (see redirect in Nginx config in seamless mode docs)

In dev mode, seamless is also default but, for convenience, Volto does the redirect, so you don't have to deal with CORS.

So http://localhost:3000/++api++ -> RAZZLE_API_PATH

You can do crazy things like:

RAZZLE_DEV_PROXY_API_PATH=http://2021.ploneconf.org:8080/Plone yarn start

(provided you have access to the port) and develop locally pointing to an external server.

See How to use environment variables โ€“ Frontend โ€“ Development recipes โ€” Plone Documentation v6.0-dev

Follow this, and tell me what do you think.

ouch, I missed your reply :confounded: thanks for all the hints and ideas, I have to get back to this topic, but I'm running behind thousand tasks at the same time :sweat_smile:

I will make sure to report back my story :slight_smile:

Plone Foundation Code of Conduct