Repository navigation
Set up docs self-hosting #162
Description
There's a growing need for self-hosting of docs for enhanced flexibility (see also #79).
Dibs. R&D phase.
Metadata
Metadata
Assignees
Labels
No labels
{{ message }}
There's a growing need for self-hosting of docs for enhanced flexibility (see also #79).
Dibs. R&D phase.
Activity
Bloke commentedon Dec 23, 2019
cough Textpattern instance with smd_ebooks for creating offline content cough
(The plugin will need tweaking for 4.8)
Honestly I can't see anything in Jekyll we can't do better or more efficiently in Txp. We have articles in sections, permlinks, markup, better search, header/footer, includes that are more flexible via forms and shortcodes, ...
Run the Jekyll pages through pandoc to convert from Markdown to Textile, or install Markdown as a textfilter and just port the content as-is.
If we can squirt collaborative changes from the GitHub repo to the Txp filesystem to rebuild the DB as part of a git post-commit hook or CI pipeline, we should be able to rebuild the changed docs with some script-fu.
petecooper commentedon Dec 23, 2019
@Bloke - I'm inclined to agree. I'm learning CI + Pandoc at the moment, so we'll see what the new year brings.
wion commentedon Jan 2, 2020
Considering the relatively low volume of docs content (and let's recognize that as by design), and the greater control Txp would provide over includes, URL redirecting, etc. I have to agree.
You could even do a flat-file site and keep it under version control. Version control is a nice thing, actually.
I don't think it's important to convert Markdown back to Textile, since we already went through that dance of going the other way. Screw that. Just add wet_markdown and use Textile for new docs only, if that's really a big deal.
That said, I don't want anything to do with the actual migration process. I know I've been in 'beast-mode', as Pete put it recently, but I'm just trying to make up for where I dropped the ball a few years back, get broken/lagging docs completed and improved. And I recognize some other editorial needs I'm happy to give attention to, to stabilize. But I'm aiming to get back to much less 'beast-mode', as it were. My objective here is get the content architecture square and then put myself on editor cruise-control so that I can return energy to my own writing.
So as long as this doesn't create any additional work for me that I haven't already shouldered myself, I have no objections.
petecooper commentedon Jan 2, 2020
Thanks @wion - I do not want to create any additional work for anyone, and certainly not undo any work done.
philwareham commentedon Jan 2, 2020
So.. you'd need to:
If those hurdles can be overcome, I'm interested.
petecooper commentedon Jan 2, 2020
This is what's keeping me away from Textpattern as-is. On the one hand - yes - CMS, and we're literally managing content here, but on other hand, it doesn't feel like the right tool for the job.
Something more automated would be better, I think - even a self-hosted Jekyll in the first instance would be minimal effort to get going an replicate the GitHub delivery but with redirect trimmings and other stuff.
Flat files, static site generator, version control baked-in, make it wicked-fast, spit out compiled versions (EPUB, PDF, MOBI, etc) as part of the GitHub CI job, rinse and repeat.
(Edit: just my 2c, of course.)
Bloke commentedon Jan 2, 2020
Suits me fine. If self-hosted Jekyll (or equivalent) is an option then go for it. I only mentioned Txp since it seemed like a good fit, but I'm by no means married to the idea if the obstacles are less than optimal to overcome. Go with whatever is easiest, most flexible and allows us to retain version control.
philwareham commentedon Jan 2, 2020
Sounds fine to me too, would be handy to use proper Jekyll plugins and proper SSL, redirects, etc. instead of the locked-down GitHub Pages version of Jekyll. I have no idea how best to achieve that but a quick web search brings this...
https://styxit.com/2017/09/13/self-host-github-pages-on-digital-ocean.html
If someone wants to have a stab at it then please go ahead. :)
petecooper commentedon Jan 2, 2020
Dibs. Won't be for a while, but I'll take it.
philwareham commentedon Jun 30, 2020
Short-term (before we potentially move to self-hosted Jekyll), GitHub now allows you more control over your Jekyll site as long as you deploy with GitHub Actions.
See https://jekyllrb.com/docs/continuous-integration/github-actions/
This now allows for third-party Ruby plugins and other customisations over and above the restricted GItHub Pages builds.
Will investigate at some point in the future.
[-]Investigate self-hosting of docs[/-][+]Investigate self-hosting and offline compiling of docs[/+]petecooper commentedon Jul 11, 2020
Folding this in so I can close it: #79
30 remaining items
wion commentedon Dec 7, 2020
Long out of the loop. Sorry. Just curious if we lose repo versioning user docs when going to a self hosted install.
petecooper commentedon Dec 7, 2020
Nope.
Repo operations won't change. The publishing target (?) will, so we'll have more control over it and be able to do more stuff, but no functionality is taken away.
wion commentedon Dec 7, 2020
Still github or something else?
wion commentedon Dec 7, 2020
Okay, I see. Thanks.
petecooper commentedon Dec 7, 2020
Still GitHub. Still all the same stuff here, perhaps a repo name change to reflect the move away from GitHub publishing infra, but we'll be running a self-hosted Jekyll with all the trimmings we need, which is a conscious move to not reinvent the wheel etc.
[-]Set up docs self-hosting and automatic compilation to ebook formats[/-][+]Set up docs self-hosting[/+]petecooper commentedon Feb 8, 2022
Initial commentary on beta site linked in #162 (comment) – subject to change.
The build appears to work OK, but we have an issue with
jekyll-pwaas seen here: lavas-project/jekyll-pwa#39, specifically:Not a deal breaker, as far as I can tell, but something to be aware of.
For now, I'm going to set up a regular
crontask to get the docs repo on a regular basis instead of the webhook stuff as mentioned in #162 (comment) – some trivial Bash is more efficient (for me, at least) than learning about webhooks and the associated stuff.Search appears to be a little faster on self-hosted Jekyll. Still not stellar but we can faff with that after the other stuff is sorted.
The Nginx config is a little different to PHP web apps, but easily managed.
petecooper commentedon Feb 8, 2022
To do:
bundleviacrontab(non-root user) on rebuild script.petecooper commentedon May 16, 2022
FYI docs site is now self-hosted. It's not pretty behind the scenes – but it works, it's automated, and we have some snagging to fix re: deprecated and EOL gems. I'll start another issue for each of those items.
Initial files for search update/fix