Environment Variables Setup¶
Environment variables are very important in a system like Runestone - they are a way to provide values for secrets that need to be kept private (and thus can’t live in the code itself which is publicly accessible). They are also used to provide startup time flexibility to define how various components will work. Some environment variables are important on the host side (h), some are important on the docker side (d), and some are important on both sides (b).
Make a .env File¶
You need to make a .env
folder in the root level of your repository to define environmental variables.
There is already a sample.env
file in the repository root, you should copy that sample into a file named .env
.
The .env
file is read by docker-compose and used to set environment variables in the docker containers. If you installed poetry-dotenv-plugin
, poetry will also automatically read it on the host side.
Note
If you chose not to install poetry-dotenv-plugin
, you will need to manually define the host (h) environment variables listed below in your login profile (.bashrc, config.fish, .zshrc, etc).
The .gitignore
file is set to ignore .env
, so your local configuration will not be checked into git.
Setup .env Values¶
The .env
file defines the variables listed below. The default values for most of them should be fine - the ones you are most
likely going to want to change are BOOK_PATH
, DEV_DBURL
, and DC_DEV_DBURL
.
Core variables:
BOOK_PATH
- (h) This is the path to the folder (on the HOST) that contains all of the books you want to serve. So if you are running docker on a mac and your books are in/Users/bob/Runestone/books
then you would set this to/Users/bob/Runestone/books
. It is recommended you make a folder for this purpose that is outside of the Runestone repository itself. Set this variable to point at that folder.COMPOSE_PROFILES
(h) - This is a list of profiles that you want to use when running docker-compose. The default isbasic
which starts the database in docker. If you want to run the production profile you would set this toproduction
which will start pgbouncer. If you want to run the servers in dev mode (not in docker) you would set this todev
. If you want to run the author server you would set this toauthor
You can also combine profiles by separating them with a comma. For examplebasic,dev
would start the database in docker and the servers on the host.DEV_DBURL
(b) - This is the URL that is used to connect to the database in development. You need to set it based on whether you are going to run the database through docker (default, simpler) or manually on your local machine (more flexible). See Database Options for more information on the choices.If you are running a postgresql container with the other servers through docker, you should set this to:
postgresql://runestone:runestone@localhost:2345/runestone_dev
If you are using postgres on your local machine, set this to:
postgresql://runestone:runestone@localhost/runestone_dev
DC_DEV_DBURL
(d) - This is the URL that is used to connect to the database in docker-compose development.If you are running a postgresql container with the other servers through docker, you should set this to:
postgresql://runestone:runestone@db/runestone_dev
If you are using postgres on your local machine, set this to:
postgresql://runestone:runestone@host.docker.internal/runestone_dev
There are a number of other variables - none of them are important unless you are running in production.
DBURL
(b) - This is the URL that is used to connect to the database in production.DC_DBURL
(d) - This is the URL that is used to connect to the production database in docker-compose. If this is not set it will default to$DBURL
. This is useful if you want to use a different database for docker-compose than you do for development.SSH_AUTH_SOCK
(h) - This is the path to the ssh agent socket. This is used to allow the docker container to use your ssh keys to use rsync to deploy books to the workers. You must set this on the host side, typically by runningeval $(ssh-agent)
from bash. You will also want to runssh-add
to add a key to the agent. Both of these can be done in your .bashrc file. If you are using a different shell you will need to figure out how to do the equivalent. This is only important if you are running in production mode behind a load balancer.JWT_SECRET
(d) - this is the secret used to sign the JWT tokens. It should be a long random string. You can generate one by runningopenssl rand -base64 32
You should set this to the same value in all of the services.WEB2PY_PRIVATE_KEY
(d) - this is the secret that web2py uses when hashing passwords. It should be a long random string. You can generate one by runningopenssl rand -base64 32
You should set this to the same value in all of the services.SERVER_CONFIG
(d) - this should be production, development, or test. It is used to determine which database URL to use.WEB2PY_CONFIG
(d) - should be the same value asSERVER_CONFIG
. It is used to determine which database URL to use. This will go away when we have eliminated the web2py framework from the code base.RUNESTONE_HOST
(d) - this is the canonical host name of the server. It is used to generate links to the server. For development you should just set it tolocalhost
. In production it should be something likerunestone.academy
orrunestone.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. For development purposes you should not set this variable. In production it should be something likerunestone.academy
orrunestone.academy:8000
if you are running on a non-standard port. You would typically only need to set this or RUNESTONE_HOST.NUM_SERVERS
(d) - this is the number of workers you are running. It will default to 1 if not set. This is only important if you are running in production mode, behind a load balancer.
Note
Host Side Development Notes
When you are starting one or more servers directly on the host (not in docker) then you will also want to define most of the docker only variables on the host side in order for your servers to be configured properly. This is another good reason to use the dot-env plugin for poetry.
Here is a summary of the profiles and services available and which should be set to start the various services. Again, remember that you can combine profiles by separating them with a comma. For example basic,dev
would start the database in docker and the servers on the host.
Profile |
db |
pgbouncer |
jobe |
book |
runestone |
nginx |
assignment |
worker |
author |
nginx_dstart_dev |
---|---|---|---|---|---|---|---|---|---|---|
default |
no |
no |
yes |
yes |
yes |
yes |
yes |
no |
no |
no |
basic |
yes |
no |
yes |
yes |
yes |
yes |
yes |
no |
no |
no |
production |
no |
yes |
yes |
yes |
yes |
yes |
yes |
no |
no |
no |
dev |
no |
no |
yes |
yes |
yes |
yes |
yes |
no |
no |
yes |
author |
no |
no |
yes |
yes |
yes |
yes |
yes |
yes |
yes |
no |