Documentation is unclear

[Myridium]

Hi, thanks for working on this great project and sharing it with the community.

I am trying to understand how this software operates at a high level, and looking over the installation procedure, and I can't understand it. I'm not new to generating certificates SSL certificates, reverse proxies, docker, or Linux administration in general. I just can't understand the instructions from a legibility perspective.

Examples:

This is the entirity of the README.md explanation of what this software is and what features it offers, at a high level: rmfakecloud is a clone of the cloud sync the remarkable tablet is using, in case you want to sync/backup your files and have full control of the hosting/storage environment.. Questions:

1. Does this software emulate a ReMarkable server, or the tablet? This quote says that it's a clone of the cloud sync that the remarkable tablet is using, implying that it acts just like a tablet that connects to the ReMarkable official servers. But I thought this software was meant to replace the ReMarkable server. Which is it?
2. What advantages does this offer over the basic ReMarkable server? Presumably it allows the user more control over their data. I assume that notebooks are stored unencrypted on disk (in a docker volume) and so can be manipulated? Are they in a proprietary format? Can I convert them to PDF? Is there software that reads them? It would be good to place this software in context.
3. What exactly does this server spoof? Does it also tell the ReMarkable about registered external storage providers? Does
4. Does the sync method of this software inherit all the bugginess and brokenness of ReMarkable's own sync? Will I see any benefit in sync performance using this software? Maybe the installation steps involve telling the ReMarkable to sync in a different way, like with rsync or something.
5. Does rmfakecloud offer a CLI interface? A GUI interface? Etc.

Next I'm reading the tablet.md. I'm expecting instructions to redirect the tablet to use my own server rather than ReMarkable's. This shouldn't be too complicated. Maybe modifying a file or two. Questions:

1. It says "There are several ways to make it work, choose whatever works for you". Make what work? Then, there are three (four?) methods listed. The first uses a heading which is a smaller font size and says Automatic. Then, Variant 1, Variant 2 and Variant 3 are listed afterwards. I take this to mean that the first part is, well, automatic and I can skip it. But then why would it be listed? I'm not sure. It asks me to just run an "automagic" script, so I guess you mean it's a script. I don't know what the word automatic adds here except to confuse. You could say that it automates the first setup variant Variant 1 when you run the script. It also has no explanation about the changes that will make to my ReMarkable, how to do undo those changes if required, but also no explanation for how it will automatically know what my custom server's domain name is. The script cannot possibly know that. This cannot be automatically accomplished. So what is this script? It is listed as an alternative to any of the following methods, but it cannot possibly be fully automated. If it's an interactive script then you should say so.
2. generate a CA and host certificate for *.appspot.com -- is the *.appspot.com to be taken literally, or do we fill in our hostname somewhere? This would be cleared up if it was explained what the purpose of doing this is. I don't know what appspot.com is.
3. The quote: A reverse proxy rmfakecloud-proxy has to be installed run rmfakecloud on whichever port you want, you can use either HTTP (not recommended) or HTTPS, generate a new cert for the url you chose e.g with Let's Encrypt. There are two run-on sentences here ...has to be installed run rmfakecloud... and also ...you can use [x], generate a new.... Also, where should the reverse proxy installed? On the tablet or on the rmfakecloud host? Why do I have to use a custom reverse proxy program, when reverse proxying is a routine procedure for networking applications? What does the script actually do? What do you mean by you can use either HTTP or HTTPS? What does use HTTP or use HTTPS mean in this context? One does not "use HTTP/s" when installing a reverse proxy. One can configure HTTP, and one can configure HTTPS, and these are not mutually exclusive options. Moreover the reMarkable sync protocol is, well, a protocol. We don't have control over whether it uses HTTP or HTTPS, so I cannot understanding the meaning of this. It's not a choice we can make-- we must use whatever the protocol demands. All of this can be clarified if you explain what the purpose of this reverse-proxy software is. I can only take a guess: does it take the reMarkable sync protocol traffic (which was redirected to 127.0.0.1 via modifying the hosts file) and redirect it to our custom server? In that case, why not just use our server's IP or hostname in hosts? Does using a reverse proxy somehow get around a invalid certificate problem? I don't know. I don't know what the reverse proxy's role is in all of this, and I'm just inferring the purpose of 127.0.0.1 redirects in the hosts file. You should explain what each step is doing and why.
4. set the STORAGE_URL to point to this address (this thing the device can resolve/see e.g the reverse proxy, public dns etc) -- it says set the STORAGE_URL. So, it's not an environment variable to be exported to be used by the next script fixsync.sh. So what exactly is the STORAGE_URL? No idea.
5. generate the certs from Variant 1, you get them (proxy.crt, proxy.key, ca.crt) and trust the ca.crt - how does one trust the ca.crt? If I knew more about using certificate authorities, then I would understand this. But I don't know and I don't understand.
6. Windows/Mac Desktop Client -- wait what? Client software? What client software? I thought this was server software. ???
7. modify the hosts file (\system32\drivers\etc\hosts) add the same entries as on the tablet -- this makes no sense. The host machine does not need its hosts file changed. What? Oh, are you referring to the ReMarkable apps on Windows and Mac?

Then in Variant 3:

1. Same as Variant2, but instead of modifying any hosts file, make the changes on your DNS/router: add the host entries directly on your router (Hosts in OpenWRT) -- it's really annoying have to back-check and cross-validate steps across methods. Please just copy/paste. It takes no time and it makes it easier to understand. Also what is the hosts entry on my router? I've never heard of such a thing, and most routers certainly wouldn't allow changing it. Also why do we have to change anything with our router? Router connected to the network of the host or the tablet? We don't necessarily have control over either. This whole thing doesn't make sense. Also what the heck is OpenWRT? Never heard of that either.
2. Oh boy, now I have to carefully cross-reference variants 1, 2 and 3 just to complete variant 3.
3. trust the ca.crt - again, don't know how, or why. In fact I don't even know where to find ca.crt.
4. I don't think it says anywhere here what records to actually add to the DNS. So I don't know what the DNS settings have to do with this variant.
5. PROS: a bit easier, you can you even the mobile apps if you manage to install the root ca. CONS: you can't use the official cloud anymore due to the mangled DNS. How does one "install a root certificate authority". One cannot "install a certificate authority". I guess you mean the certificate? Why would we install the certificate that generated earlier...? I don't even understand why we generated that certificate (or how, since you say for *.appspot.com but I don't own that domain so how could I generate a certificate for it?), much less why the certificate should be required on the devices which hook into rmfakecloud.
6. you can't use the official cloud anymore due to the mangled DNS well considering the instructions did not include any changes to the DNS settings, I think it'll be fine.

I'd like to try this software but the instructions make no sense to me. I don't know how other people manage. Maybe you just need to be an expert in this stuff to get it.

[murchu27]

That's a whole lot of questions, to be honest it would be hard to address all of this in one issue.

I agree that there are parts of the documentation that are not clear. But without meaning any disrespect, have you actually tried any of the instructions (e.g., the installation instructions at the top of README.md)? All of your questions seem like "theoretical" questions, rather than specific questions that have come up from issues you've had.

I suggest we take this piecemeal. Let's get the software set up on your server - to answer your first question, this software mimics the reMarkable servers, not the tablet. Once you're set up, I think that will give you a better vantage point for the questions you're asking.

First step is to clone the repo, and build the binaries (as per the installation instructions I mentioned earlier). Any issue with that, just give a shout here! 🙂

[murchu27]

...it would be hard to address all of this in one issue.

Just to be clear, I'm not saying that we won't address your questions! But your issue covers a lot of distinct questions in different parts of the repo (even though it can all be grouped under documentation). We might need to discuss the wording/legibility of each unclear section, which will get very messy under one issue.

Let's create some tasks, and address each issue separately. And again, if you can try to install the software (which I will help you with), it will be easier for you to help us with the parts that you're finding unclear 😊

• [ ] Documentation cleanup: README.md
• [ ] Documentation cleanup: tablet.md

[Myridium]

Thanks @murchu27 . That's right, these are theoretical questions. But, one does generally need to know what some software on their device is going to do before installing it... otherwise, there are security issues, but even if you trust it, I won't know if the software is right for me or not without actually trying it. It is rather time-consuming to set up new software, and it can leave junk on the system and changes that need to be reverted as part of uninstall. I also don't know what this software is going to do in the end. Another example: since this is faking the RM servers, can it also spoof the subscription tiers? Since that is a service enabled by the ReMarkable servers, after all. It may not be worth the time investment for me, depending on what exactly this software will do.

[Eeems]

Another example: since this is faking the RM servers, can it also spoof the subscription tiers?

What purpose would that serve? You just get full access to all implemented features in rmfakecloud. No need for subscription tiers.

It is rather time-consuming to set up new software, and it can leave junk on the system and changes that need to be reverted as part of uninstall.

https://github.com/toltec-dev/toltec/pull/448 the toltec rmfakecloud-proxy package that is currently in testing will simplify the setup a ton for new users. You'll still have to stand up your own rmfakecloud instance to point it at though.

[ddvk]

Actually, rmfakecloud emulates and uses the highest tier.