seravo / docs Goto Github PK

Description
Currently there is no clear documentation on how one can and should start developing this repository. There is no clear documentation on setupping the local development environment either. We should document what is the desired way to setup and start developing or testing the repository and its contents locally. For example, I had never developed our docs and the crucial setupping & testing command were provided in #68. If setupping and running is so easy that it only requires couple of commands, it should be quite trivial and documented as well.

@sjaks, Would you be interested in documenting the setup process or in general improving the documentation?

Currently private Composer repos are briefly mentioned at https://seravo.com/docs/configuration/composer/#paid-wordpress-plugins-and-composer

This isn't easy enough. We should have a concrete example how to install for example Advanced Custom Fields Pro or Polylang Pro using Composer, which customers could just copy-paste to create their own working setups.

It would spice up the docs nicely if there were some embedded videos (published at youtube.com/seravo) or small gif animations or fancy asciinema or showterm recordings covering the typical workflow.

We should experiment with this a bit.

Any information on what schedule/how often the certificate generation runs would be great. I migrated a production-ready site on a Saturday and now am left wondering if this is something that requires assistance from Seravo as the website is throwing an error Your connection is not private on browsers.

Even better would be the option to run Certbot through something like 'wp issue certificate'.

With man pages the double dashes in front of command flags are being converted to an en dash, a single character. This can cause confusion if a user is copying flags or example commands straight to their terminal.

Under wp-test-whitelist man page we have two examples. They are formatted like this when copied:

wp-test-whitelist –add “https://example.com/favicon.ico 404 (Not Found)”

wp-test-whitelist –add “.*example\.com/mylibrary\.js.*404.*” –regex

The add and regex flags don't have double dashes in front of them but instead the en dash. This seems to be happening on any man page with any occurrences of double dashes.

We already cover "Curl to shadow" at https://seravo.com/docs/deployment/shadows/ but there should be a more speficic section on how JSON-API can be tested, where the shadow endpoint is, how the shadow routing works etc.

Instructions in https://seravo.com/docs/development/how-to-install/ don't seem to be very up do date. Vagrant >= 2.2.7 supports VirtualBox 6.1 and I saw no performance issues using it.

Some things to note:

• Latest Vagrant and VirtualBox work together
• Latest Vagrant not available even in Ubuntu 20.04 LTS so instructions maybe needed
• Old versions of https://github.com/Seravo/wordpress Vagrantfile don't work at all with the latest Vagrant

Was there reasons to recommend VirtualBox 5.2 other than incompatibility of 6.1 and slowness of 6.0? Should we start recommending VirtualBox 6.1?

When I pushed to this repo I received an email from github:

The page build completed successfully, but returned the following warning for the gh-pages branch:
You are currently using the 'redcarpet' Markdown engine, which is no longer supported by GitHub Pages and may cease working at any time. To ensure your site continues to build, remove the 'markdown' setting in your site's '_config.yml' file and confirm your site renders as expected. For more information, see https://help.github.com/articles/updating-your-markdown-processor-to-kramdown/.
For information on troubleshooting Jekyll see:
https://help.github.com/articles/troubleshooting-jekyll-builds
If you have any questions you can contact us by replying to this email.

While reading https://seravo.com/docs/man/wp-check-remote-failure/ I notice that no link from https://seravo.com/docs/get-started/available-commands/ leads to that page.

Maybe we need a round of manual reviewing of that page so it links to all current commands we have? (minus deprecated and unnecassary ones)

Due to historical reasons GitHub pages required that the contents was on a branch named gh-pages. I suspect this is not required anymore, not at least if GitHub pages deployment is done using GitHub Actions.

TODO:

• Rename branch gh-pages to master to follow the convention of regular git repos
• Activate GitHub Actions to deploy from master to seravo.com/docs: https://github.com/Seravo/docs/actions/new
  

Our current seravo.com/docs has served us well, but it might need a structural upgrade.

Biggest annoyances at the moment:

• Pages are not easy to render locally, the experience is much more archaic than e.g. compared to sites that use Hugo
• Instead of every article being a post with a date, they should be dateless pages so the "information architecture" would be correct.
• Our man pages are not part of the docs and there is no easy way to append them there.

I have been looking at how nice the Pydantic docs look like, and they have a built-in search (just like we need) with some additional features, and is build using Python and all build code and Github Actions are available publicly.

As of today we now have the man pages included in seravo.com/docs and that is a great leap forward 🚀

There are however some details that might need to be addressed. For example, currently the search feature does not extend into the contents of the man pages.

Demo:

Instructions on how to reset a shadow via wp-admin suggest Tools -> Shadows. This path seems to be deprecated as shadows are found under Site Status in wp-admin and there is no option Shadows under Tools menu.

https://seravo.com/docs/deployment/shadows/#graphical-option-via-wp-admin

Customer suggested: We should have a simple table listing which commands are available everywhere, which are only in production and which only in dev/local.

The man pages include some links. Currently they are not rendered into real clickable links in seravo.com/docs:

It would be nice if they could be rendered. Links to external man pages could go to manpages.ubuntu.com, e.g. http://manpages.ubuntu.com/manpages/focal/en/man1/rdiff-backup.1.html

Docs should include instructions on how to change the domain of a site.

Background: I did check the Seravo nginx and the module is installed: --with-http_realip_module. I then added the configuration from Cloudflare, but it's reporting (what I think is) the Seravo's internal reverse proxy as origin IP. In this case it was 172.17.42.1.

Solution:
You have to add an additional line to your custom nginx config: set_real_ip_from 172.17.42.0/16; which will also look up the CF-Connecting-IP header on all requests coming through that rev proxy.

Please advise if it's necessary to add other subnets to the config, but here it is in case you want to add to docs:

# - Seravo
set_real_ip_from 172.17.42.0/16;

# - IPv4
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 104.16.0.0/12;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 131.0.72.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;

# - IPv6
set_real_ip_from 2400:cb00::/32;
set_real_ip_from 2405:8100::/32;
set_real_ip_from 2405:b500::/32;
set_real_ip_from 2606:4700::/32;
set_real_ip_from 2803:f800::/32;
set_real_ip_from 2c0f:f248::/32;
set_real_ip_from 2a06:98c0::/29;

real_ip_header CF-Connecting-IP;

The headings on the seravo.com/docs should have an easy to use anchor link, preferably something the users can click to save the link on the clipboard.

We already have the basic functionality present, as in: https://seravo.com/docs/configuration/nginx/#how-to-create-your-own-rules

E.g. _posts/<date>_<pagename> to eg. category/something/feature.md

This would be a cleaner structure. Current date based blog stucture is useless in the seravo.com/docs documentation reference.

The Pagespeed documentation at https://seravo.com/docs/configuration/nginx/#the-pagespeed-module doesn't really explain why the filters would benefit the user. There should be some brief description for each filter and then a use-case example.

It would also be good to maḱe the installation steps more detailed. Currently, the user is solely told to "enable" it.

Once a new Vagrant image is released, document the new config items introduced in Seravo/wordpress#99

Also:

Also probably should be added to https://seravo.com/docs/development/configure-vagrant-box/ sometime soon (also realised that production=>user for the SSH user is not documented).

The page https://seravo.com/docs/configuration/php7-hhvm/ has "PHP 7" in the title. Now with PHP 8, the title should be just "PHP version" or something. Also it would be better if the URL was https://seravo.com/docs/configuration/php-versions/ (and with the old URL redirecting to the new one to avoid link rot).

Naturally the page itself also needs to be updated to include PHP 8 and drop PHP 7(.0). While 7.2 and 7.3 continue to be available, the page should clearly state that PHP 7.4 is currently the recommended version everybody should be using.

A link to https://www.php.net/supported-versions.php would also nicely complement it.