[Enhancement] Automated site preview deployments for PRs

[visortelle]

Search before asking

• I searched in the issues and found nothing similar.

Motivation

Before merging any PR to the site, seeing how site and docs changes look in a browser is useful.

Currently, the reviewer needs to have a local repo copy, a proper Node.js version, switch to the proper branch, install dependencies, and finally run the site using npm start.

This process isn't hard for someone who reviews PRs regularly, but for others, this is an additional obstacle that can prevent them from taking a look.

Imagine you made a visual change or worked on some tutorial or blog post. By having automated deployments you'll be able to share this link to the mailing list or Slack and anyone interested will be able to read and review your changes without the need to do any additional actions.

I think it could bring more eyes to the review process and contribute to improving documentation quality over time.

Solution

Use Vercel for automated deployments.
https://vercel.com/

Taking into account the number of PRs to the apache/pulsar-site repository per month, the free Vercel plan should be enough for the near future. The next paid plan is $20 per month which isn't much.

We currently use this approach for reviewing this PR: apache/pulsar-site#789
The PR branch preview: https://pulsar-site-2024-updates.vercel.app/

I also tried it with a PR by another person's fork here:
https://github.com/visortelle/pulsar-site-2024-updates/pull/1

You can see that the preview deployment has been successfully created:

https://pulsar-site-2024-updates-8c5d4i9z9-visortelle.vercel.app/books/

Implementation

• No code changes are needed.
• Setup takes 15 minutes.
• The free Vercel plan implies that a single user has access to the Vercel project that connects the GitHub repo to Vercel. I'm going to request access after being sure that it will be approved. Should I contact anyone in ASF infra beforehand?
  

Alternatives

• Any other cloud provider than Vercel that simplifies this process.
• Not involve 3rd party services and automate this process using the existing ASF infra resources. It would take more time to implement and additional cost for maintenance.

Anything else?

• The build time doesn't impact GitHub Actions resources. Vercel uses its own CI.
• The Vercel approach covers most, but not 100% of cases. For example, docs for the previous Pulsar versions won't be published this way. Building all the previous version docs would make CI build time much longer.
• The need for automated feature branch deployments was also mentioned in this comment:
  Add doc for transform functions before sinks pulsar-site#543 (comment)

Are you willing to submit a PR?

• I'm willing to submit a PR!

[asafm]

@lhotari Do we need ASF approval for this?
@visortelle Do you add in github secrets your own user for deployments? How do we keep more than 1 person in that app so if you step away, others can chime in on this?

[visortelle]

Do you add in github secrets your own user for deployments?

@asafm I didn’t touch any secrets or env variables. Nor in forked GitHub repository settings nor in the Vercel project settings. It works the same way as you build the site with the yarn build command locally and then run yarn serve.

How do we keep more than 1 person in that app so if you step away, others can chime in on this?

There are few options:

• The simplest solution is just to ask me to delete the Vercel project and someone else will be able to set it up again 🙂
• Someone from the ASF infra team can remove the GitHub <-> Vercel link without the need to ask me. Then create a new Vercel project.
• We can use a shared GitHub account like pulsar-service-account and set up the link on its behalf. Then in the case of the bus 🚌 just change the credentials.

[lhotari]

@lhotari Do we need ASF approval for this?

@asafm I don't think so, but I could always be wrong. :) @dave2wave knows the right answers.

[asafm]

@visortelle Can more than one person be added to this Vercel account in case you are on vacation and we want to fix something?

[visortelle]

Can more than one person be added to this Vercel account

@asafm not in the free plan.

It's doubtful I will be on vacation in a place without Internet access 🚀🌔🏝️

The setup takes a few clicks. Switching to another's person account would take 15 minutes if the approval process is quick.

If we try it and find it useful, I can describe the setup process in a markdown document.

[visortelle]

I requested access to apache/pulsar-site. Let's see what will happen :)

[asafm]

@visortelle, I think you need to file a JIRA issue to have them approve this pasted above.

Another question - would the mechanism of GitHub pages work for our use case?

[visortelle]

Another question - would the mechanism of GitHub pages work for our use case?

@asafm it would, but it needs a bit of bash/whatever code like here:

https://github.com/haskellfoundation/haskellfoundation.github.io/pull/170/files#diff-3ed7460912c35ce883da3c35afc7975ffb28bdeac52bb95569b71b641b9a4300

Plus additional scripts to handle not only branches but also PRs. Otherwise, the PR submitter would need to make additional steps to make the deployment available.

I'm not sure that anyone wants to maintain it.
If it's possible to implement without touching the code, I would prefer to go this way.

Also in the case of using Vercel, you're getting a sub-domain for each deployment like <branch_name>.pulsar-site.vercel.com
In the case of using GitHub pages, you'll need to set the branch deployment at an extra HTTP route like <github_pages_domain>/<branch_name>/....
I suppose many links may be broken in this setup and would need to be fixed. Again, unnecessary extra work.

[visortelle]

I submitted a JIRA ticket: https://issues.apache.org/jira/browse/INFRA-25567

[visortelle]

A good example of using Vercel for sites with public source code is HashiCorp.

You'll find it across most of their projects including Terraform, Consul, and Vault.

Forked repository PR deployment example: hashicorp/terraform#34375

[visortelle]

Small clarification on how it works in HashiCorp.

PRs from forked repositories require approval by someone who maintains the site.

Example: hashicorp/terraform#34517

[visortelle]

The ASF infra team suggested taking a look at .asf.yaml

Ref: https://issues.apache.org/jira/browse/INFRA-25567

It supports branch deployment branch deployments, but:

• doesn't support forked repositories PR deployments
• doesn't care about deleted branches
• doesn't automatically add a deployment link to a PR page. Users should manually submit this link as a part of the PR comment, or know how to get this link

Regarding Vercel, the answer is NO

I'll probably experiment with .asf.yaml in the future, but closing for now.