Migrate StackStorm blog and CMS to GH Static Pages

[blag]

April 2021 @StackStorm/tsc 1 hour meeting will take place on Tuesday, 27th Apr 2021, 09:30 AM US Pacific.
See #33 for more info about how to join.

Agenda

Migrating from our current CMS to a static site generator

• Need to migrate CMS pages
  • Don't need to migrate all of them in our current CMS, just ones that are still used
• Need to migrate the entire blog
• Should migrate the final generated HTML+CSS and not just the stored Markdown
• Use Hugo? (suggested by @nmaludy)
  • Migration tools
• Where to host?
  • GitHub Pages?
    • Blog posts would become PRs to that repo
      • All draft blog posts would be public (eg: blog posts on security would need to be written privately)
    • Automatic deployment with GitHub Actions
    • Is there any reason why this should not be GitHub Actions?

Deliverables

• A plan to migrate to the new CMS, including old content
• INTERMEDIATE: Export the website as static HTML content at https://github.com/StackStorm/stackstorm.com/
• Switch the traffic to a new GH Pages static version
• Cancel the hosting (we lose $ every month on our current host)
• Enable https://www.netlify.com/ integration for PR preview
• Export website content as hugo templates and configure CI/CD for deploying to GH static pages
• Crate custom theme with hugo to be 1:1 match with the old website and blog (help wanted!)

[arm4b]

+100

The advantages of migrating the entire stackstorm.com website and blog to GH Static pages:

• Transparency
• zero infra management (hosting, plugins, etc)
  • $35/mo savings for WP hosting as a bonus
• We don't need to create user accounts or have someone who's responsible for it, admins, access levels, etc
• 100% security, no dynamic pages
• Collective TSC + Community PR reviews for the blog posts
• Partners can update their records via PR
• Everyone (TSC or community) can propose/contribute a guest Blog post

Having said that, it perfectly aligns with the OSS project values, mechanisms, and needs.

[nmaludy]

Example of how we did this at Encore:

• We had two repos

  • A Hugo repo that contained our template and content markdown files: https://github.com/EncoreTechnologies/blog
  • The statically generated site for GitHub pages: https://github.com/EncoreTechnologies/encoretechnologies.github.io
    • This repo needs to be name .github.io and the contents will be automatically hosted on github pages

• Procedure for writing a new blog post

  • Fork blog/ and make a new blog md file by running $ hugo new content/blog/2021/03/mypost.md this would copy the markdown template from archetypes/blog.md
  • Fill out the .md file with your blog post in markdown
  • Make a PR against blog/ repo

• Procedure for deploying the site

  • in the blog/ repo, run bin/deploy.sh (could be automated with a GitHub action)
  • this updates the git submodule in the public directory by generating the new hugo site to that directory, committing and pushing
  • when you git push to .github.io it automatically deploys the new site for you

[arm4b]

Example with GH Pages: https://github.com/stackStorm/stackstorm-ha/tree/gh-pages -> https://helm.stackstorm.com/

[blag]

Meeting Notes

• Prototyping - @armab and @nmaludy, and possibly @mickmcgrath13 (since he has previous experience with the site)
• Create the repo on GitHub - literally named stackstorm.github.io
  • Can we do two GHP repos - one for the base site (repo name: stackstorm.github.io) and another for the blog (repo name: blog)? That would help keep just anybody from proposing changes to the main StackStorm website.
• Export directly from WP to Hugo
  • If that doesn't work, we can try to export our blog to Jekyll
    • Then if we need to convert from Jekyll to Hugo, there are plugins to do that
• Use a DNS CNAME record to point stackstorm.com to stackstorm.github.io
  • GitHub Pages natively supports this

[arm4b]

Some notes from Slack:

1. StackStorm Exchange operates via static pages too: https://github.com/StackStorm-Exchange/web#deploying-new-versions

This website is hosted by Github Pages. When code is merged to master, if it passes linting and tests, it will automatically get pushed to the gh-pages branch, and served at https://exchange.stackstorm.org/

2. If we could get it operated as a single repo like stackstorm.com via different branches for posts and generated content it would be great as from time to time we'll need to edit not just posts but also pages. Avoid context-switch. Otherwise, go with @nmaludy experience with 2 repos.

3. Worth exploring the conversion plugin: https://github.com/SchumacherFM/wordpress-to-hugo-exporter. Otherwise https://wordpress.org/plugins/jekyll-exporter/ -> Hugo.

4. Explore more recommendations at: https://gohugo.io/tools/migrations/

5. The main difficulty could be converting the existing stackstorm.com wordpress theme into a hugo-compatible template for the 100% visual match. Otherwise, find the new nice-looking Hugo theme just for the blog posts as @nmaludy suggested.

6. Let's target to deliver this in approx. 2 months.

[arm4b]

7. An intermediate step would be going with the https://wordpress.org/plugins/export-wp-page-to-static-html/ first. Eg. just export the entire stackstorm.com to a statically generated content hosted on github, before templating it in Hugo. Note: keep the WP installation for a while as a plugin will be needed to export/convert the actual posts to hugo.

[cognifloyd]

https://github.com/StackStorm/stackstorm.com -> https://stackstorm.github.io/stackstorm.com/

I added a gha workflow that regenerates with hugo and deploys automatically to the gh-pages branch on push.
I added a random hugo theme.
I moved stuff around to be in the expected hugo dirs.

Most of the pages still aren't building with hugo. Maybe they were generated for a different version of hugo than I'm using? Dunno.

[arm4b]

Nice! Thanks a lot, @cognifloyd, very helpful! 👍

We'll need to adjust the theme, design, and pages next to make sure everything together looks exactly as old stackstorm.com, incl. page structure and URLs.

[arm4b]

The website + blog is now exported to a temporary https://stackstorm.xyz/ as raw HTML.
The HTML is available in the git branch: https://github.com/StackStorm/stackstorm.com/tree/website-html

I've made the last WP + DB dump backup to AWS S3 if we'll need it sometime in the future.

I couldn't find any issues so far or missing pages with a new version.
I plan to shut down the WP hosting next week and switch to the new raw HTML GH Pages version.

Updated the initial Issue with the plan and tasks.

[arm4b]

FYI stackstorm.com traffic switch from the old hosting to https://github.com/StackStorm/stackstorm.com/ GH Static pages (raw HTML for now) is completed.

[arm4b]

Tasks for managing and improving stackstorm.com via new GH Pages were created in the https://github.com/StackStorm/stackstorm.com/issues. There are really good first issues for someone willing to contribute, one PR per change.

From the list, creating Hugo template for stackstorm would be the most complex work.