Improve documentation

deploy/docker/README.md

@@ -18,4 +18,4 @@ would attempt to create the initial user again.
 `winget` requires repositories to run under `https://`. For production use, you
 now need to set up a reverse proxy that accepts `https://` requests and forwards
 them to `localhost:8000`. To test things on your local PC, you can use the
-[SSL Proxy](../local/sslproxy) provided in this repository.
+[SSL Proxy](../sslproxy) provided in this repository.

deploy/local/README.md

@@ -1,29 +1,9 @@
 # Running winget.pro on your own computer
 
-Running winget.pro locally is mostly done during development. For production
+Running winget.pro locally (that is, on the same PC where `winget` commands are
+then used to install software) is mostly done during development. For production
 use, consider one of the other deployment options.
 
-## Install a local SSL certificate
-
-`winget` only allows `https://` sources. This means that if we want to run
-locally, then we need a self-signed SSL certificate for `localhost`.
-
-[`localhost.pfx`](sslproxy/localhost.pfx) can be used for this purpose. It was
-created from [these instructions](https://gist.github.com/alicoskun/57acda07d5ab672a3c820da57b9531e3).
-To install it, issue the following in a Powershell Admin prompt:
-
-```bash
-$password=ConvertTo-SecureString "12345" -asplaintext -force
-Import-PfxCertificate -FilePath localhost.pfx Cert:\LocalMachine\My -Password $password -Exportable
-Import-Certificate -FilePath localhost.cert -CertStoreLocation Cert:\CurrentUser\Root
-```
-
-To remove it later, run `mmc`, click `File/Add or Remove Snap-in` then
-`Certificates/Add/My User account` then `Finish` and again for
-`Computer account`. Then click `OK`. Then delete `localhost` expiring 2041 from
-`Current User/Personal`, `Current User/Trusted Root Certification Authorities`,
-and `Local Computer/Personal`.
-
 ## Set up the development environment
 
     pip install -Ur requirements/base-full.txt
@@ -33,23 +13,29 @@ and `Local Computer/Personal`.
 1. Run `python manage.py migrate`
 2. Run `python manage.py createsuperuser`
 3. Run `python manage.py runserver`
-4. Log into `/admin` and create a _Tenant_.
+4. Log into `/admin` and follow the instructions to create a _Tenant_.
 
 ## Start the server
 
+Execute the following command if it is not still running:
+
     python manage.py runserver
 
-Then:
+This starts to server on `http://localhost:8000`. `winget` however requires the
+server to accept `https://` requests. This can be done during development with
+the SSL proxy from this repository.  Please see the
+[`sslproxy/` directory](../sslproxy) for instructions. Typically, you will
+run the following command:
 
-    python sslproxy/sslproxy.py
+    python sslproxy.py
 
-Then you can add the REST source (note the `httpS`):
+Now you can add a REST source in winget (note the `httpS`):
 
     winget source add -n dev -a https://localhost:8443/ab... -t "Microsoft.Rest"
 
 Here, `ab...` is the UUID of the Tenant.
 
-Then you can perform queries against the new source. Eg.:
+You can perform queries against the new source. Eg.:
 
     winget search "search term" -s dev
 

deploy/sslproxy/README.md

@@ -0,0 +1,42 @@
+# SSL Proxy
+
+`winget` only allows `https://` sources. In production, you will have a web
+server such as Nginx that accepts `https://` requests and forwards them to the
+winget.pro Python server.
+
+The files in this directory provide a mini web server that can accept https://
+requests and forwards them to a winget.pro instance that does not support
+https://. This is useful for development and testing.
+
+## Install the self-signed SSL certificate
+
+The implementation here requires us to have a self-signed SSL certificate for
+`localhost`. [`localhost.pfx`](../sslproxy/localhost.pfx) can be used for this
+purpose. It was created from
+[these instructions](https://gist.github.com/alicoskun/57acda07d5ab672a3c820da57b9531e3).
+To install it, issue the following in a Powershell Admin prompt:
+
+```bash
+$password=ConvertTo-SecureString "12345" -asplaintext -force
+Import-PfxCertificate -FilePath localhost.pfx Cert:\LocalMachine\My -Password $password -Exportable
+Import-Certificate -FilePath localhost.cert -CertStoreLocation Cert:\CurrentUser\Root
+```
+
+To remove it later, run `mmc`, click `File/Add or Remove Snap-in` then
+`Certificates/Add/My User account` then `Finish` and again for
+`Computer account`. Then click `OK`. Then delete `localhost` expiring 2041 from
+`Current User/Personal`, `Current User/Trusted Root Certification Authorities`,
+and `Local Computer/Personal`.
+
+## Run the SSL proxy
+
+Once you have installed the self-signed SSL certificate above, you can run the
+following command to start the SSL proxy:
+
+    python sslproxy.py
+
+By default, this accepts SSL requests on port `8443` and forwards them to
+`localhost` on port `8000`. You can use command-line arguments to change these
+parameters:
+
+    python sslproxy.py <local_port> <dest_host> <dest_port>