Adding some more information to the readme, #45

[snake14]

Description:

A customer recommended adding more information about SSH tunnelling and about an alternative. Fixes: #45

Review

• [ ] Functional review done
• [ ] Potential edge cases thought about (behavior of the code with strange input, with strange internal state or possible interactions with other Matomo subsystems)
• [ ] Usability review done (is anything maybe unclear or think about anything that would cause people to reach out to support)
• [ ] Security review done
• [ ] Wording review done
• [ ] Code review done
• [ ] Tests were added if useful/possible
• [ ] Reviewed for breaking changes
• [ ] Developer changelog updated if needed
• [ ] Documentation added if needed
• [ ] Existing documentation updated if needed

[AltamashShaikh]

@snake14 Also we should make this bold to make it more obvious.

[gitressa]

New SSH tunneling text

Thanks! But It is still not clear to me where to run ssh -NL 3307:localhost:3306 targetuser@targethost ... my machine, the source or target? Perhaps the text could start with outlining this?

Now

ssh -NL 3307:localhost:3306 targetuser@targethost

This essentially maps port 3307 [...]

Better?

ssh -NL 3307:localhost:3306 targetuser@targethost

Run the above command on THERIGHTPLACE. This essentially maps port 3307 [...]

Replace THERIGHTPLACE ^^ with the either "your own machine", "the source server" or "the target server".

About siteid

In my opinion, it would be better to expand the text, and spell it out, so that it is really clear what will happen. Also, perhaps move it up the page "To start a migration execute ..."?:

The migration tool will create a new website in the target Matomo, using the next available siteid, and copy all the data from the source website to this newly created target website. Remember to update the tracking code to match the new siteid.

To start a migration execute [...]

[gitressa]

Migrating on target server

An alternative to using an SSH tunnel is to make a backup of your MySQL database, copy it to the new server, import it into the database, and then migrate using that database name.

Maybe emphasize that you should probably import it into a temporary, separate database?

An alternative to using an SSH tunnel is to make a backup of your MySQL database, copy it to the new server, import it into a temporary, separate database, and then migrate using that database name. Remember to delete the temporary database after completing the migration, and checking that everything works.

[snake14]

Thank you for the feedback @gitressa . It's no wonder you were still confused, because I was apparently confused and wrote the new text backwards. I have corrected that and tried to incorporate your suggestions.

[gitressa]

Thanks @snake14, the text is clearer now, and makes sense. I had prepared a longer text about the reversals, but thought I'd start here and see if you caught them, which you did :-)

However, one sentence still puzzles me:

The targethost should be replaced by a valid IP or domain name referencing the server you are migrating to and must be accessible to the server that you are migrating from.

How do you make the targethost accessible to the server that you are migrating from? Do you need to create a SSH user on source server and upload SSH public keys to target server? If that's the case, it should probably be mentioned.

Also, has SSH tunneling been verified to work by one of you guys?

[snake14]

Thank you for your graciousness @gitressa . I have added a little more detail and some more links for reference.

I haven't tried SSH tunnelling with the Migration plugin, but I have used it in the past. It's common to use it to map a local port to a remote database.

[gitressa]

Thanks @snake14, the latest version with the added details about SSH requirements makes sense, answering the most relevant questions. So that part is done.

Ideally (for the perfect review) someone would go through the steps in the guide, and be able to complete a migration between two firewalled servers, to verify that the steps outlined give enough info to complete the task.

Either by someone with very basic SSH knowledge, or someone who "adapts" the tech knowledge level mentally, and tries to think as such a user (if it makes sense). But I also realize that this takes more time and resources, and maybe not realistic ...

[snake14]

Thank you @gitressa . Yeah. We usually try to do functional testing as part of our code reviews, but that's not really applicable for a readme change. I can see if a member of our support team can take a look at the changes and see if they have any feedback.

[gitressa]

Sounds good. Thanks for being open to updating the documentation, and being so patient with all my suggestions.