Migration from CHT 3.x on docker-compose to CHT 4.x on k3s

[henokgetachew]

Description

• How to migrate a CHT 3.x deployment that's on docker-compose to a single node k3s instance
• How to migrate a CHT 3.x deployment that's on docker-compose to a 3-node clustered couchdb on k3s.

I have made them separate files because it became complicated as a one file with if/else conditions. It makes them more readable this way.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[dianabarsan]

Nice. I'm not sure we need two pages, since there is a lot of repetition. Or is there a way we can get the common parts together and just reference them? I think there was one instance of this ...
Ah:

cht-docs/content/en/building/reference/_partial_cht_api.md

Line 4 in 8101da9

hide_summary: true

This page is reused in some other page like: https://github.com/search?q=repo%3Amedic%2Fcht-docs+_partial_cht_api&type=code

So I think all common elements, in both PRs, can be collected into partials and shared across.

[mrjones-plip]

Great work here - thanks Henok!

I think using an shared _include-file is the way to go for content that overlaps per Diana's suggestion. Let me know if you need a hand!

I think the link titles are a bit confusing currently:

• 4.x
  • Data migration to 4.x
  • Docker Compose to K3s Clustered Migration
  • Docker Compose to K3s Single-Node Migration

Instead, I think we can clean them up to be more clear (possibly a sub-directory? seems a bit too nested...we'll go flat for now!):

• 4.x
  • Migration: 3.x to 4.x
  • Migration: 4.x Docker to 4.x k3s (Multi-node)
  • Migration: 4.x Docker to 4.x k3s (Single-node)

I've made suggested code changes for this, but can't edit the Migration: 3.x to 4.x document link in the PR, please make the change though.

As well, we should make each number a heading so it's clickable and appears in the right hand side TOC. I've made suggested code changes for this.

Variables should always be the same to reduce confusion (eg username vs admin-user vs saved-user-login). I've made suggested code changes for this, but may have missed some!

It's incredibly daunting have a YAML file and try and read through any changes that are needed. I recommend we:

• always list out the items that need changing
• always use the same syntax to highlight an item need changing using angle brackets: <change-me>
• Always use the same name for the same value in and out of the YAML(mentioned above)

[henokgetachew]

Accepted most of the suggested changes. I'm now extracting the partial.

[henokgetachew]

FYI, I'm rebasing this PR against the main branch.

[mrjones-plip]

Coming along! Nice work here.

See below for requested changes.

It's also not clear what the "Data migration to 4.x" doc is for. Is that for both docker and k3s? Is that more generically for how to migrate from 3.x to 4.x using the couchdb-migration tool? I think we should update the link title to be more accurate. Maybe that's:

Data migration to 4.x -> Migration: Docker 3.x to Docker 4.x - but I'm not sure!

As well, we need to clarify on the page itself as it just says:

Guide to migrate existent data from CHT 3.x to CHT 4.x

But doesn't qualify it any further. The two new pages do a great job of this!

[dianabarsan]

Cool! Left some minor comments :)

[dianabarsan]

It could be tough to keep the documentation and the helm repo in sync. Can we, instead of inlining the whole contents of the values file somehow link to the current version of it?

[henokgetachew]

I have somehow struggled with this too. The original values.yaml in the helm charts is much larger and robust as it accounts for all the different scenarios. I originally thought that the comments on the yaml would be enough to guide people to the correct final configuration of what should be removed or what should be included. However, that hasn't been the case. That's why I decided to add example config of the various scenarios in the docs. Although not ideal, we'd have to remember to keep the docs in sync when we add/remove features from the helm-charts.

[henokgetachew]

It's also not clear what the "Data migration to 4.x" doc is for. Is that for both docker and k3s? Is that more generically for how to migrate from 3.x to 4.x using the couchdb-migration tool? I think we should update the link title to be more accurate.

@mrjones-plip I have renamed the file and changed the description as well.

[mrjones-plip]

Very close! I noticed a few discrepancies in how we name inline variables that we want the user to replace - I've made suggestions to make these all homogeneous.

I see you made some changes to the frontmatter of the internal Medic EKS guide. This is not what I was suggesting. Instead, I suggest we change the name of "Migration from CHT 3.x to CHT 4.x" document here - this document is not clear what it applies to. However! After reviewing this PR for a third time, I think we should just create a new directory to simplify the left hand navigation and page titles. ALL The documents are 3.x to 4.x and they're ALL from docker hosting ;) I propose we take this:

and create a "Migration guides" directory and rename the links like so:

[dianabarsan]

I'm leaving this to @mrjones-plip to finish full review. Thanks for making all the changes!

[henokgetachew]

Good idea. I have re-organized docs into a migration dir.

[henokgetachew]

@mrjones-plip I have also updated the links in other docs referencing the migration page. The build is passing and I think iit should work fine. Let me know if anything is broken or feel free to also push directly to the branch if you think there should be a different folder structure.

[mrjones-plip]

cool - I'll take a look later today and get back to you!

[mrjones-plip]

Thanks so much! Made a minor fix in b742888 , but this is good to go. w00t \o/