docs: document run.py vs readalongs/run.py

readalongs/run.py

@@ -8,6 +8,14 @@
 #   It seems Werkzeug doesn't play well with SocketIO, so use SocketIO to run the app
 #   Watch this issue: https://github.com/miguelgrinberg/Flask-SocketIO/issues/894
 #
+#   This file might seem redundant with ../run.py, but it's not: this here is invoked
+#   by "readalongs run", through click and Flask. Flask supplies the "run" command by
+#   default, using Werkzeug by default, bug we provide our overriding implementation
+#   here.
+#
+#   By contrast, ../run.py can be invoked directly to manually run the app on a
+#   hard-coded port. This is also what is used by default in our Dockerfile.
+#
 ######################################################################################
 
 from readalongs.app import app, socketio

run.py

@@ -1,6 +1,9 @@
 #!/usr/bin/env python3
 
-""" Run ReadAlong Studio as web application """
+""" Run ReadAlong Studio as web application
+
+Define the PORT environment variable to specify which port to use (default: 5000).
+"""
 
 import os