Ningle Tutorial 5: Environmental Variables

Contents

• Part 1 (Hello World)
• Part 2 (Basic Templates)
• Part 3 (Introduction to middleware and Static File management)
• Part 4 (Forms)
• Part 5 (Environmental Variables)

Introduction

Welcome back, before we begin looking at databases we need to look at storing process related data in the application environment, this month will be a relatively short, but important part in this series.

If you are unfamiliar, there’s a methodology called 12factor for building web applications that advocates for storing variable data in environment variables. In anticipation of working with databases that are going to need database names, potentially usernames and passwords etc, we need a system to load this data into our system without writing this potentially sensitive information down in the application code itself.

Environmental Variables are just that, variables defined in the environment of a process. Your operating system defines a number of these, for example, your system will have an area where files might be stored temporarily, and a program may run on different systems, but if both systems have an environmental variable TMP then the program can read the value of the TMP environmental variable and use the directory the system specifies, making it portable across systems without needing to change the code. You just read the value defined by the TMP environmental variable from the system and that’s it!

When a process starts, it gets a copy of all system defined environmental variables, although a process generally can’t override the values to affect other processes, it is, however, possible to change existing ones or add new ones to the running process, which is what we are going to do here. We have a process we want to run, but want to hide sensitive information in the environment and so will inject new environmental variables into the running process without adding to the system environmental variables for any other process.

Typically we do this by creating a file (usually called .env) that will define the new values, and this file will be loaded as the program starts, importantly this file will NOT be stored in version control, otherwise we wouldn’t hide the data, just move it to a different file. It is very important to ensure that you ignore this file!

In order to use this technique we will be using the cl-dotenv package, so first ensure you have added it to your dependencies in the project asd file.

:depends-on (:clack
             :cl-dotenv
             :ningle
             :djula
             :cl-forms
             :cl-forms.djula
             :cl-forms.ningle)

Integrating the package is quite simple, just below where we create the application object in main.lisp, we use the package to load in the custom environmental variables.

(defvar *app* (make-instance 'ningle:app))

(dotenv:load-env (asdf:system-relative-pathname :ningle-tutorial-project ".env"))

It is important to ensure we have a .env file prior to starting the application though! We are likely going to use sqlite (at least in the beginning) so we need to tell our application where to store the database file, for now that will be the only thing we store in the .env file, we can always add to the file as/when we need to, and this tutorial serves as an introduction to injecting environmental variables, so if it works for one, it’ll work for many! Please note, this .env file must be in the root of your project.

DBPATH=~/quicklisp/local-projects/ningle-tutorial-project/ntp.db

To confirm this works, we will add a format expression to prove things are as we need them to be, in the start function, we use the uiop package (which comes installed with sbcl) to get the variable.

(defun start (&key (server :woo) (address "127.0.0.1") (port 8000))
    (format t "Test: ~A~%" (uiop:getenv "DBPATH"))
    (djula:add-template-directory (asdf:system-relative-pathname :ningle-tutorial-project "src/templates/"))
    (djula:set-static-url "/public/")
    (clack:clackup
      (lack.builder:builder :session
                            (:static
                             :root (asdf:system-relative-pathname :ningle-tutorial-project "src/static/")
                             :path "/public/")
                            *app*)
     :server server
     :address address
     :port port))

If you start the application now, you should see the value being loaded and printed out.

Test: ~/quicklisp/local-projects/ningle-tutorial-project/ntp.db
NOTICE: Running in debug mode. Debugger will be invoked on errors.
  Specify ':debug nil' to turn it off on remote environments.
Woo server is started.
Listening on 127.0.0.1:8000.
#S(CLACK.HANDLER::HANDLER
   :SERVER :WOO
   :SWANK-PORT NIL
   :ACCEPTOR #<BT2:THREAD "clack-handler-woo" {1005306473}>)

Conclusion

To recap, after working your way though this tutorial you should be able to:

• Explain what an environmental variable is
• Explain why environmental variables are important to application security
• Use cl-dotenv to load a file containing data to be loaded into the process
• Use Lisp code to display the new loaded environmental variable

Github

The link for this tutorial code is available here.

Resources

• 403 Status
• 12factor
• Environmental Variables
• cl-dotenv