Original post is here: eklausmeier.goip.de
1. Task at hand. Find a convenient and performant way to show content to inhouse people, and also be able to show other content to external customers. The content should ideally not be visible to the general public. The content in question does not change frequently, i.e., generating the content via a static site generator (SSG) is entirely feasible. An example for inhouse documents: legal documents for employees only. An example for external documents: release notes, software manuals, etc.
This memo gives some recommendations on how to achieve this goal.
Here is a list of hitherto used systems:
- Notion: offering wikis, notes, plans, etc.
- Zenhub: planning and tracking
- Slack: chat, messages, simple workflows
- GitHub: version control
The team is using the following technologies:
- TypeScript: programming language
- Angular: web framework
- WebStorm: IDE
There are more systems and technologies in use. The above simply highlights some crucial ones and gives a first impression with what kind of methods and tools people feel comfortable with, and they have their main area of expertise.
2. Solutions. Below is a list of possible approaches for the stated problem.
- Called solution A. Set up a web-server on a cloud platform. I.e., set up NGINX on either Amazon ec2, or IONOS, Hetzner, OVH, DigitalOcean, etc. There is a plethora of offerings for this. New content is then copied to this server.
- Called solution V. Use Vercel and a static site generator (SSG) like Eleventy. New content can be pushed to Vercel via GitHub actions. Eleventy is a static site generator written in JavaScript.
- Called solution W. Use WordPress on one of the very many providers for this software, e.g., WordPress.com, IONOS, etc.
There are many more possible solutions to the problem.
3. Discussion and evaluation. Pros and cons of the above-proposed solutions. Short reminder: A content delivery network (CDN) is recommended in case the content is to be distributed worldwide. For example, you want your web content shown in China and Europe in a speedy way. The CDN copies the content to various diverse geographical locations. That way the content is near to the end user and loads quickly. The earth is so huge that even the speed of light can become one limiting factor, not the only one, of course.
There are two different authorizations required: internal staff, and external customers.
One approach is to use two different DNS entries, e.g., internal-corp.vercel.app
, and external-corp.vercel.app
.
The 1st solution, solution A: web-server on a cloud platform like Amazon.
Pros | Cons |
---|---|
Easy to purchase | Needs constant updates: OS + web-server |
Well understood | Difficult integration for advanced authorizations like SAML |
Easy use of .htaccess for simple authorizations |
No CDN out of the box |
Easy to add other services, like demo app |
The 2nd solution, solution V: Use Vercel with SSG.
Pros | Cons |
---|---|
Authorization integration | |
No software updates for OS + web-server | |
CDN built in |
Delving into the 2nd solution a little bit more related to authorization:
- For legal documents only directed to internal staff, one can use a list of trusted IPs in Vercel. Thereby limiting the access to these documents only to internal staff. Internal staff does not need another password to memorize.
- For external customers a simple Password Protection can be used.
- Alternatively, a full blown SAML Single Sign-On can be configured in Vercel.
Publishing content to Vercel can be fully integrated to GitHub: A change to a GitHub repo will automatically trigger a deploy to Vercel. This functionality seems to be attractive for publishing the release notes. This integrates nicely into a CI/CD workflow.
[mermaid] flowchart LR N["Notion"] --> G["GitHub"] --> E["Eleventy"] --> V["Vercel"] Z["Zenhub"] --> G S["Source code"] --> G [/mermaid]
Vercel was founded in 2015 by Argentinian entrepreneur Guillermo Rauch. Vercel distributes content to 18 regions, including Paris, Hong Kong, and Singapore. Therefore Chinese customers should see web content quickly.
The static site generator Eleventy was proposed as it is written in JavaScript, and this programming language and ecosystem are well established in the targeted environment. It is actively developed and has a vibrant community.
An alternative static site generator is Simplified Saaze used by this blog. It has the advantage that it is easy to understand, and fast in its operation. It has the disadvantage that it uses PHP and C, and therefore might not fully resonate with the target environment already used.
The 3rd solution, solution W: WordPress.
Pros | Cons |
---|---|
Easy to edit existing content | Plugins and Varnish required for proper performance |
Contains e-mail newsletter functionality | Plugin required to display 3rd party data |
Contains comment system | Not very performant out of the box |
From the above, solution V is most advantageous
4. Disclosure. The author has no financial interests. He does not get any kickbacks by any of the above-mentioned vendors.