Tidying up sample.env

docs/source/developing.rst

@@ -218,10 +218,31 @@ These two sets of variables can be identical, but they are separate because it i
 * ``RUNESTONE_HOST`` *d* - this is the canonical host name of the server.  It is used to generate links to the server.  It should be something like ``runestone.academy`` or ``runestone.academy:8000`` if you are running on a non-standard port.
 * ``LOAD_BALANCER_HOST`` *d* - this is the canonical host name of the server when you are running in production with several workers.  It is used to generate links to the server.  It should be something like ``runestone.academy`` or ``runestone.academy:8000`` if you are running on a non-standard port.  You would typically only need to set this or RUNESTONE_HOST.
 
-Variables that are important for the host side are probably best set in your login shell environment (such as a .bashrc file) But you can also set them in the .env file and as long as you have a RUNESTONE_PATH set commands like ``rsmanage`` and ``runestone`` will try to read and use those variables.  Variables that are important for the docker side are best set in the ``.env`` file.  The docker-compose file pulls
-When you are doing development you may want to set these in your login shell, But they can all be set in the ``.env`` file in the top level directory.  This file is read by docker-compose and the values are passed to the containers.  You can also set them in the ``docker-compose.yml`` file but that is not recommended.  The ``.env`` file is also used by the ``build.py`` script to set the environment variables for the docker-compose build.  As of this writing (June 2023) rsmanage does not know about the ``.env`` file so you will have to set them in your login shell if you want to use rsmanage.
-
-
+Variables that are important for the host side are probably best set in your
+login shell environment (such as a .bashrc file) But you can also set them in
+the ``.env`` file and as long as you have a RUNESTONE_PATH set commands like
+``rsmanage`` and ``runestone`` will try to read and use those variables.
+
+When you are doing development you may want to set these in your login shell,
+But they can all be set in the ``.env`` file in the top level directory. This
+file is read by docker-compose and the values are passed to the containers. You
+can also set them in the ``docker-compose.yml`` file but that is not
+recommended. The ``.env`` file is also used by the ``build.py`` script to set
+the environment variables for the docker-compose build. As of this writing
+(June 2023) rsmanage does not know about the ``.env`` file so you will have to
+set them in your login shell if you want to use rsmanage.
+
+An alternative to setting ``RUNESTONE_PATH`` is add the ``poetry-dotenv-plugin``
+to your ``poetry`` installation. It will cause commands like ``poetry shell`` to
+also import variables from the ``.env`` file which means that you will have them
+when you run ``runestone`` and ``rsmanage`` from withen the shell you launched
+with ``poetry shell``. To install the plugin run:
+
+``poetry self add poetry-dotenv-plugin``
+
+Note, however, that plugins in ``poetry`` are global, not per-project, so if you
+have other ``poetry`` projects with ``.env`` files that you `don`t` want slurped
+into your ``poetry shell`` environment you may not want to install this plugin.
 
 
 Getting a Server Started 

sample.env

@@ -1,48 +1,45 @@
 # Copy this file to .env docker-compose will read and use the values from here.
-# The build.py script is also aware of this file
+# The build.py script is also aware of this file and if you run `poetry self add
+# poetry-dotenv-plugin` when you run `poetry shell` it will also pick up these
+# variables and add them to your environment.
 
 # Where is the runestone app located (inside the container)
 RUNESTONE_PATH = /usr/local/lib/python3.10/site-packages/rsptx/web2py_server/applications/runestone
 
-# Database URLs
-# You may want to have a couple of different environment variables set up that essentially point
-# to the same database.  Therefore we have two variables. DEV_DBURL and DC_DEV_DBURL. The DC variant 
-# should only be set in this file for use with docker-compose.  But if you don't set it and you
-# have a DEV_DBURL variable set in your shell compose will use that as a back up.  In My development
-# environment I have:
-# DEV_DBURL= postgresql://user:pass@localhost/runestone_dev
-# DC_DEV_DBURL=postgresql://runestone:runestone@host.docker.internal/runestone_dev
-
-# Uncomment one or more of these.  If you run a database on the host then the DEV_DBURL uses 
-# a nice docker trick to connect to it.
-# DBURL = postgresql://username:password@production_host/runestone
-# TEST_DBURL=postgresql://runestone:runestone@host.docker.internal/runestone_test
-DC_DEV_DBURL=postgresql://runestone:runestone@host.docker.internal/runestone_dev
-DC_DBURL=postgresql://runestone:runestone@host.docker.internal/runestone
+# Database URLs: You may want to have a couple of different environment
+# variables set up that essentially point to the same database. Therefore we use
+# one set of variables for use within docker, prefixed with DC_ and another pair
+# for use outside of docker. The DC variants should only be set in this file for
+# use with docker-compose. (If you don't set the DC_ variables, docker compose
+# will fall back to the other pair.)
+
+DBURL = postgresql://runestone:runestone@localhost/runestone
+DC_DBURL = postgresql://runestone:runestone@host.docker.internal/runestone
+
+DEV_DBURL = postgresql://runestone:runestone@localhost/runestone_dev
+DC_DEV_DBURL = postgresql://runestone:runestone@host.docker.internal/runestone_dev
 
 # Server configuration (production, development, or test)
-# You should not set this to test as that is for our testing framework, not for 
+# You should not set these to test as that is for our testing framework, not for
 # people who are just testing out Runestone.
 SERVER_CONFIG=development
-WEB2PY_CONFIG=$SERVER_CONFIG
+WEB2PY_CONFIG=development
 
 # The path to runestone books (on the host) In the container is set to /books
-export BOOK_PATH=~/Runestone/books
-
+BOOK_PATH=~/Runestone/books
 
 ## !! change these !!
 # This replaces the private/auth.key file for web2py
-WEB2PY_PRIVATE_KEY=sha512:24c4e0f1-df85-44cf-87b9-67fc714f5653
+WEB2PY_PRIVATE_KEY = sha512:24c4e0f1-df85-44cf-87b9-67fc714f5653
 # This is the secret key for the javascript web token
 JWT_SECRET = supersecret
 
 # Set up host names
 # localhost is ok for development, but you should set this to the real hostname
 # if running a remote development server or definitely for production
-RUNESTONE_HOST=localhost
+RUNESTONE_HOST = localhost
 # for production where you run a front end load balancer
-LOAD_BALANCER_HOST=localhost 
+LOAD_BALANCER_HOST = localhost
 
 # If you want nginx to install a certificate
-# CERTBOT_EMAIL=myemail@foo.com
-
+# CERTBOT_EMAIL = myemail@foo.com