Consider publishing DIY ngrok/pagekit instructions

[mrjones-plip]

These were published internally, but there's no reason they can't be published externally as is, there's no sensitive information.

Diagrams were made on drawio and originals are attached here: diy.ngrok.images.zip

---

DIY ngrok/pagekite for Android app testing

Overview

To avoid using ngrok or pagekite to allow remote access to your dev instance (https://github.com/medic/cht-core/blob/master/DEVELOPMENT.md#ngrok), you can use a remote linux server to terminate HTTPS connections with free Let's Encrypt certs and reverse proxy this traffic back to a local dev instance over an SSH tunnel:

Prereqs

This guide assume:

• You have a local dev instances set up of cht-core https://github.com/medic/cht-core/blob/master/DEVELOPMENT.md
• You have medic-android repo checked out and can compile the android app from scratch https://github.com/medic/medic-android/
• You have the generic Medic Mobile app installed on your android device https://play.google.com/store/apps/details?id=org.medicmobile.webapp.mobile&hl=en_US
• You have an Ubuntu >18.04 server with a public IP and a DNS entry that you can SSH into and have sudo on
• You have apache >2.4.29 installed on the Ubuntu server and can add a new vhost to it, including an SSL cert. (nginx could be used instead as well, but not covered here)
• You have certbot installed from letsencrypt.org

For reference any of the cheap servers out there (Digital Ocean has a $5/mo server https://digitalocean.com/) will enable you to do this.

Warning!!1!

Be extra careful with this process! The end result will be that your development instance will be accessible to the internet. If you have simple logins and passwords like "admin/test.223" because you thought it was just your local dev instance and it doesn't matter, now it matters! Whenever you're not using the SSH tunnel for testing, shut it down so not remote access is allowed.

Never expose a development instance to the internet where you've replicated production data locally. Well, maybe not never, but with extreme care and intention.

Steps

1. Create a DNS entry. Let's assume it's cht.example.com. It should point to your Ubuntu server

2. On your Ubuntu server, create a new apache vhost in /etc/apache2/sites-available/100-cht.example.com.conf with the following contents:

   <VirtualHost *:80>
       ServerName cht.example.com
       RewriteEngine on
       RewriteRule (.*) https://cht.example.com%{REQUEST_URI}
   </VirtualHost>
   
   <IfModule mod_ssl.c>
   <VirtualHost *:443>
       ServerName cht.example.com
       SSLEngine On
       <IfModule mod_headers.c>
           Header always set Strict-Transport-Security "max-age=63072000; preload"
       </IfModule>
       RewriteEngine on
       Include /etc/letsencrypt/options-ssl-apache.conf
       SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
       SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
   
       ProxyPass / http://localhost:8081/
       ProxyPassReverse / http://localhost:8081/
       RequestHeader set X-Forwarded-Proto "https"
   </VirtualHost>
   </IfModule>

3. Enable the new site: a2ensite 100-cht.example.com
4. Restart apache and ensure there's no errors: apachectl restart
5. Create the TLS certificate: certbot -d cht.example.com
6. When prompted choose no redirect: "No redirect - Make no further changes to the webserver configuration."
7. Restart apache and ensure there's no errors: apachectl restart
8. In a browser, test that you can connect to your server with no errors at https://cht.example.com (you may get a 500 error, but you shouldn't get any TLS errors)
9. Ensure your cht-core local dev instance is running by going to http://localhost:5988/
10. On your local dev box, set up the SSH tunnel with: ssh -NT -R 8081:127.0.0.1:5988 cht.example.com
11. This assumes your local username is the same as it is on cht.example.com. This command will hang and you may exit when down with "ctrl + c"
12. In a browser, test again that you now see your local dev instance and it loads correctly at https://cht.example.com
13. If needed, reset the Medic Mobile app on your phone so that it prompts which instance to use
14. In the app on your phone, choose "custom" for which instance to use and enter https://cht.example.com. You should now see your local dev instance in the medic mobile android device. Happy testing!

Your traffic is now flowing like this from the SSH command above:

[mrjones-plip]

closing as I some how duped this in #341