Specify a root path for serving

[mbostock]

The code currently assumes that the project will be served at the root of a domain and generates absolute paths starting with slash. We should support a serve root option (different from the current source root option) that allows the site to be served from a subpath.

[pettiross]

Is there a reason to provide a different serve root instead of building with relative paths? It feels like a point of failure to have the build process managed by a viz dev need to align with the relative URL on a server that might be managed by someone else.

[mbostock]

I believe the only case where we use absolute paths currently are file attachments (including local imports that are promoted to file attachments). File attachments live in dist/_file to avoid potential namespace collision with generated HTML files. It’s true we don’t need these to be absolute paths; we could rewrite these as relative paths e.g. ../_file/foo.js.

That said, there might be some cases where we need to know the serve root regardless. For example if we want to generate a sitemap.xml (see Plot’s for example), we need to know not just the serve root but the host origin as well.

[mbostock]

I expect this will be a blocker for deploying to Observable?

[mbostock]

This is not yet fixed. Still to-do:

• A base option or some such config to specify the base path for serving the preview
• File attachment paths are still hard-coded to be under /_file

[Fil]

FileAttachments, sure!

slightly obsolete, see comment below

To clarify the first point (base), what we want is:
observable dev --base https://example.com/directory/

• a) the dev server opens at http://127.0.0.1/directory/ and serves from that base URL; a user can locally change their /etc/hosts to point example.com to 127.0.0.1 and have the correct URL honored by the dev server.
• b) absolute URLs, when needed, are https://example.com/directory/… (not http://127.0.0.1/directory/…)

observable build --base https://example.com/directory/

• c) we use https://example.com/directory/ wherever we need an absolute URL
• d) we error if an absolute URL is needed and not specified

b), c) and d) are not relevant at the moment, but will be used with #168; they would also be necessary for open-graph and canonical urls.

[mbostock]

I was thinking more

observable dev --base /directory/

See:

https://github.com/observablehq/plot/blob/a0369548adc0e2126595fdab30e981df0fb59cb2/docs/.vitepress/config.ts#L11

[Fil]

Thanks! So the host part would be a host option (and if host is passed as https://example.com/directory/ we echo a friendly message). This is now issue #180.

[Fil]

It's not clear to me if we're talking of a --base switch for the dev command, a base option for the build, or both.

I can see how any of these might be useful:

• observable dev --base /directory/ runs the dev server under 127.0.0.1/directory/, allowing to verify that the pages are indeed working under the intended directory structure.
• Option base=/directory/ direct observable build to use https://example.com/directory/ as its absolute URL when needed, provided the host option is also present. It can also be passed as a base.href for the 404.html page (Generate a custom 404 page #174).

[mbostock]

It should be for both. And really it should be a config option rather than a command line flag.

[mythmon]

Just to say it out loud: the Platform build/deploy process will need to dynamically set the base path. Having some way to configure this at runtime will be needed. If it isn't built that way from the start, we'll add it as a part of the deploy command. That could be a build function that takes a target dir and a base path as parameters, maybe?

[mbostock]

the Platform build/deploy process will need to dynamically set the base path

Why is this a requirement? I can maybe see it for versioning, but in the common case we should know the slug and the user login for a project, so by extension we should also be able to predict the base path. It’s definitely possible to do what you’re describing (and it’s an example of why I’ve been advocating that we upload a “partial” build of data loader outputs, file attachments, public assets, and Markdown sources rather than uploading the fully-built static site to the platform) — I’d just like to understand the motivation.

[mythmon]

Versions are exactly why. The URLs we plan to use for the files of a project will include a unique ID per-deploy, and we don't want to put it in the hostname, as we discussed previously. That means it will be in the path. An example URL might be https://my-workspace.static.observableusercontent.com/project/${deployId}/helpers/bignum.js. (where "helpers/bignum.js" is the relative path inside the "docs" directory of the repository).

Alternatively, if every thing used relative urls (../helpers/bignum.js) we wouldn't need this, but that seems unlikely at this point if I've followed along correctly.

Note that these aren't the URLs that users will see in their browser's URL bar. That will probably be more like https://observablehq.com/@my-workspace/my-project/a-page, or maybe we'll need a Projects-specific marker in the URL like /p/@my-workspace/my-project/a-page. We haven't discussed that yet.

As for partial builds: I think that for server-side building we'll want to use the CLI as a library. We'd need a dynamic base path there too.

[mbostock]

Yeah, that sounds good. We want atomic deploys (so there’s no chance of seeing a mix of assets from different versions of a deploy due to caching), so it makes sense that we’d want a per-deploy base path. Maybe this means that observable deploy should run observable build as a subcommand, and override the base option for that build? Rather than running observable build first and then running observable deploy. Or maybe observable deploy, like I’ve been saying, doesn’t build the Markdown (just the data), and then when we do the build in the cloud we can dynamically assign the appropriate base path.

[mythmon]

Maybe this means that observable deploy should run observable build as a subcommand, and override the base option for that build?

That's what I had in mind for our first milestone. Ideally we'd be able to call into the build subcommand directly in JS instead of having to go through a subprocess. That would let use have access to more options internally than we want to expose on the CLI, if so inclined. I think we would even want a special output directory for the files we eventually upload so we don't fill the user's dist dir with a weird build.

We have been keeping the hybrid build idea in mind, and I hope we can do as a part of our v1, but it won't be a part of our Internal Access milestone.

[Fil]

if every thing used relative urls

We're almost there, all that remains is to apply the logic of #42 to _file/ links. Then there are some things that don't work well (or at all) with relative URLs. We've identified a few in #180.

[mbostock]

Now that file attachments are relative (with a fix for absolute paths still pending in #235) I’m going to call this done. We don’t need the base option for local preview, at least not yet. We can file another issue for that if there’s demand.