Textpattern docs site has moved to a new server

gaekwad · 2024-02-14 13:43:49

jakob wrote #336629:

Do I remember rightly, that this opens up the possibility to get docs search working again on Safari. Or was that a more involved process?

phiw13 wrote #336631:

The search functionality is still broken in Safari but iirc that required some code retooling, so not a regression.

Gather round, it’s story time.

The docs site used to run on MediaWiki back in the dark ages, and it was migrated to GitHub pages (hence the textpattern.github.io repo name). Since then, it has moved to our own self-hosted Jekyll instance, and more recently it’s moved to a new(er) server also running Jekyll.

On paper, Jekyll looks an absolute breeze to run: take some raw files, add a build recipe, and it spits out a heap of static HTML files. It’s great for blogs, and I’m sure it’s a really good solution for interactive site building where a person is involved.

Now, flip that on its head…I don’t want to be manually rebuilding our docs site on every commit…I want to set the server up to be as automated as possible, and the docs site comes down, gets built, and is deployed as smoothly as possible. This is what happens now, and it’s always a mess when I rebuild a server and deploy Jekyll:

Install Ruby (global)
Install Ruby Gems (to the non-root user that’s doing some of the heavy lifting)
Modify the .bashrc so interactive shell stuff works for testing
Set up & schedule the Bash script to grab the docs repo every 15 minutes
Set up & schedule the Bash script to build the site with Jekyll
Spend an hour wondering why it’s not building
Spend an hour fixing missing / outdated Ruby Gems
Spend an hour wondering why it’s still not building
Remember that the .bashrc directives need to go into the Bash build script
Cross fingers for another hour while it sort of splutters into life
Remember why Ruby + Jekyll is zero fun.

Bam, that’s half a day gone. I don’t get on with Ruby admin’ing at all, and it’s only Jekyll that needs it…so there’s a trade off with not having PHP installed, so lower resource usage, but Ruby sort of infests all manner of stuff.

And I’m the person who compiles stuff from source, keeps a tight ship server-wise, and takes pride in a fleet of server cattle. Ruby and Jekyll feels like a bodge in the grand scheme. It may well be me being curmudgeonly over something that always makes me want to hurt inanimate objects and have a dozen or more browser tabs open to fix yet another Ruby error.

What I’d like to do is move away from Jekyll, if it’s viable. I’ve opened github.com/textpattern/textpattern.github.io/issues/212 for discussion with a view to:

selecting a hosted docs service like GitBook or Read The Docs
using their search, since it just works
doing some housekeeping on the repo to get it ready for the migration

To get Jekyll search working in Safari is possible, I’m sure…I lost most of yesterday to getting a new server set up with what appears to be mostly working Jekyll, and I need a bit of a break before I go splunking in the internals to get whatever bloody Ruby Gem is needed for search to work. Leave it with me.

(Thanks for coming to my latest TedX talk.)

wet · 2024-02-14 13:53:05

Pete, may I offer you a virtual pat on the back and a warm hug? I feel your pain. From the bottom of my heart – even though I only had to make a small Jekyll site once in my life.

Be strong. This too shall pass.

gaekwad · 2024-02-14 14:15:37

wet wrote #336648:

From the bottom of my heart – even though I only had to make a small Jekyll site once in my life.

The small sites are the worst since – if you’re like me, anyway – you’re dealing a constant, nagging “there has to be a better way to do this” in the background, whereas with the bigger sites you’re at least consigned to the fact that you have to do it with Jekyll since that’s how it’s always been.

And thank you. I appreciate that more than you know. I can’t tell you how frustrating it is not being able to be definitive on something, when all else in the chain is clear as a bell.

Algaris · 2024-02-14 14:21:29

I keep hearing about Eleventy as an alternative to Jekyll. Apparently it’s built using JavaScript (Node.js), so no Ruby.

Also thank you for the hard work you’ve put into this. I’m constantly amazed at how much you do for the Textpattern ecosystem.

Last edited by Algaris (2024-02-14 14:23:16)

gaekwad · 2024-02-14 14:38:48

Algaris wrote #336650:

I keep hearing about Eleventy as an alternative to Jekyll. Apparently it’s built using JavaScript (Node.js), so no Ruby.

I had a poke around with Eleventy a while ago for another project, then looked at the NPM ecosystem that I’d need to grok and automate…and that gave me pause.

The lack of search is a pain, honestly. The irony of the docs being searchable text content for a CMS that has good search functionality (Textpattern) that’s using another entirely different CMS to display it without search functionality (my remix of Jekyll) is not lost on me.

In a future timeline, I’d love to see Textpattern be able to import a bunch of supplied, pre-formatted content and turn it into articles, images & files. We sort of have it a the moment with the setup article, but something beyond that to check for content in a given directory and then build the article scaffold…that’d be amazing.

I can bodge it with a scheduled SQL import, but that involves getting the articles from the repo, formatting them in a way that won’t snap a Textpattern instance in half, build the SQL, import it, and away we go. No Ruby. No NPM.

I’m not averse to hosting docs on a third party service that does it well. It frees up some of my time and energy to work on other things ^{that don’t involve Ruby}.

And thank you, I appreciate your kind words.

gaekwad · 2024-02-14 14:41:00

gaekwad wrote #336626:

I can power off the old server, save us some $$ and move to the next task.

This is now done. tarzan.textpattern.net is no more.

Next task: move servers to Debian 12.

Edit: this is scheduled to follow the release of Textpattern 4.9.0, so we can roll with Debian 12 + PHP 8.3. I don’t think I will have fully figured out PHP on Nginx Unit (we’re using PHP-FPM at the moment) by then, but who knows what the year will bring!

Last edited by gaekwad (2024-02-14 15:05:15)

Bloke · 2024-02-14 14:45:27

Honestly, the only reason we chose GitHub pages in the first place was so the community could own the docs and we wouldn’t have to do it. Submit PR or request commit rights and away you go.

If that’s not on the table or uptake isn’t overwhelming there’s absolutely no reason not to up sticks to a Txp instance which can do it better.

Bloke · 2024-02-14 14:49:14

And if we do move, I can feel a shell script running all the pages through pandoc coming on…

etc · 2024-02-14 14:55:28

gaekwad wrote #336652:

In a future timeline, I’d love to see Textpattern be able to import a bunch of supplied, pre-formatted content and turn it into articles, images & files. …

I can bodge it with a scheduled SQL import, …

One could also send this content to some etc_post entry point, that would then publish it as txp articles (passed via a md filter). And etc_cache could save them as static html files, that would be served when the search is not involved.

Anyway, thanks for your work and patience.

gaekwad · 2024-02-14 15:11:41

Bloke wrote #336656:

Honestly, the only reason we chose GitHub pages in the first place was so the community could own the docs and we wouldn’t have to do it. Submit PR or request commit rights and away you go.

Oh, I absolutely agree with the decision, Bloke – please don’t take my posts as gripes, far from it – GitHub Pages was basic and mostly worked until it didn’t, hence the move over to self-hosted Jekyll…we were 95% of the way there with GitHub Pages so it wasn’t a massive stretch to get over the line, it’s the underlying bullshit that’s a pain point.

Bloke wrote #336657:

And if we do move, I can feel a shell script running all the pages through pandoc coming on…

Totally! No need to reinvent the wheel. If and when I can wrap my noggin around GitHub Actions and the CI / CD tubes, there’s nothing stopping us having multiple versions spat out on each commit. EPUB docs coming to LeanPub in the not too distant future…

etc wrote #336658:

One could also send this content to some etc_post entry point, that would then publish it as txp articles (passed via a md filter). And etc_cache could save them as static html files, that would be served when the search is not involved.

This sounds far more elegant than my sledgehammer approach.

jakob · 2024-02-14 15:32:47

gaekwad wrote #336652:

In a future timeline, I’d love to see Textpattern be able to import a bunch of supplied, pre-formatted content and turn it into articles, images & files. We sort of have it a the moment with the setup article, but something beyond that to check for content in a given directory and then build the article scaffold…that’d be amazing.

👍👍👍 Just wanted to thumbs-up this – but also the other follow-up ideas. If there’s an automatable path from PR-able docs to Textpattern, that would be great!

Textpattern CMS

Textpattern CMS support forum

#13 2024-02-14 13:43:49

Re: Textpattern docs site has moved to a new server

jakob wrote #336629:

phiw13 wrote #336631:

#14 2024-02-14 13:53:05

Re: Textpattern docs site has moved to a new server

#15 2024-02-14 14:15:37

Re: Textpattern docs site has moved to a new server

wet wrote #336648:

#16 2024-02-14 14:21:29

Re: Textpattern docs site has moved to a new server

#17 2024-02-14 14:38:48

Re: Textpattern docs site has moved to a new server

Algaris wrote #336650:

#18 2024-02-14 14:41:00

Re: Textpattern docs site has moved to a new server

gaekwad wrote #336626:

#19 2024-02-14 14:45:27

Re: Textpattern docs site has moved to a new server

#20 2024-02-14 14:49:14

Re: Textpattern docs site has moved to a new server

#21 2024-02-14 14:55:28

Re: Textpattern docs site has moved to a new server

gaekwad wrote #336652:

#22 2024-02-14 15:11:41

Re: Textpattern docs site has moved to a new server

Bloke wrote #336656:

Bloke wrote #336657:

etc wrote #336658:

#23 2024-02-14 15:32:47

Re: Textpattern docs site has moved to a new server

gaekwad wrote #336652:

Board footer