Environment Variables

Application Environment Variables entered into the Satorix Dashboard are passed into the application in your Satorix Hosting Cluster through the Satorix CI/CD tool. Variables are stored with a keyed name in Gitlab’s Secret variables.

Here is a scenario for using these variables in a Rails application. The general principles are similar for most web programming languages.

Preparing your application

The satorix-rails gem provides a streamlined mechanism for a twelve-factor Rails application to interact with the Satorix ecosystem.

Add Satorix to your Rails application by including it in your Gemfile with:

gem 'satorix-rails'

Run the bundle command to install it.

Next, run the generator from a terminal at the root of your application:

$ rails g satorix:install

This creates a set of files that utilize environment variables created by default with Satorix. These include the Phusion Passenger Rails app server and the Passenger built in Nginx web server.

Configuring your application

You can configure your application on a per-environment basis using environment variables.

Default environment variables

The following default environment variables are used by the satorix-rails generated files and can be managed through the Satorix Dashboard:

SATORIX_CANONICAL_URI_HOST

Optional, a domain to rewrite all requests to by default. Setting this will make it so all requests to your site will go to the supplied domain.

Common setting:

  • www.domain.dom

SATORIX_CANONICAL_URI_PROTOCOL

Optional, the HTTP protocol to rewrite requests to.

Valid settings:

  • http
  • https

SATORIX_PROXY_IPS

Optional, used to define proxy IP addresses, for services like CloudFlare. This will allow you to get the actual client IP address accessing your site in the logs and accessible to your application.

Valid settings:

  • Space separated list of IPs or network ranges (103.21.244.0/22 103.22.200.0/22 103.31.4.0/22 104.16.0.0/12 108.162.192.0/18 131.0.72.0/22 141.101.64.0/18 162.158.0.0/15 172.64.0.0/13 173.245.48.0/20 188.114.96.0/20 190.93.240.0/20 197.234.240.0/22 198.41.128.0/17 199.27.128.0/21)

SATORIX_AUTHENTICATION_HTPASSWDS

Optional, used to control access to your site with HTTP Basic authentication. Needs to be generated in the format created by the Apache tool htpasswd -nb username password or using an online generator.

Valid settings:

  • Newline separated list of username and hashed password: 
      username:$apr1$vAxBKb8N$m0en1zabtHktHeFyT3j9y
  alsoname:$apr1$vAxBKb8N$m0en1zabtHktHeFyT3j9y

SATORIX_AUTHENTICATION_ALLOWED_IPS

Optional, used to control access to your site by bypassing the above HTTP Basic authentication. If set to all no authentication will be required. Any IP addresses or networks added here will not need to supply the username and password to access the site.

Valid settings:

  • All (all)
  • Single IP (192.168.1.2)
  • Network range (192.168.1.0/24)
  • Space separated list of multiple IPs or network ranges (192.168.1.3 192.168.2.0/24)

User defined environment variables

Starting with Rails 4.1 there is a built in configuration system utilizing the configuration file config/secrets.yml. The secrets added to this file are accessible via Rails.application.secrets.

The config/secrets.yml should be checked into version control (without production API keys of course).

The config/secrets.yml should specify valid development and test values, and be set up to pull production values from the environment variable. The environment variables do not need to follow any particular naming convention to work, a simple method is naming them the entire nested name, separated by underscores.

Prior to staging and production deployment, the configuration details needed to populate the environment variables will have to be added to the project environment in the Satorix Dashboard using the newly specified keys.

Using user defined environment variables in your application

Here is an example of configuring an email server for action_mailer to use. This set up will pull in the email server settings for your application from the ENVVARs you set in the Satorix Dashboard or it will use hard coded defaults for development and testing.

In your Rails application configuration file config/application.rb, add the following:

config.action_mailer.smtp_settings = {
  address: secrets.smtp[:address],
  domain: secrets.smtp[:domain],
  password: secrets.smtp[:password],
  port: secrets.smtp[:port],
  user_name: secrets.smtp[:user_name]
} if secrets.smtp.present?

In your Rails secrets file config/secrets.yml, add the values that we will be getting from the ENVVARS we set in the Satorix Dashboard:

# Use environment variables for 'real' secrets, and test/development in this file.
shared: &shared
  secret_key_base: <%= ENV['SECRET_KEY_BASE'] || 'mylocaldevelsecretsecretkey' %>

  smtp:
    address: "<%= ENV['SMTP_ADDRESS'] || 'localhost' %>"
    domain: "<%= ENV['SMTP_DOMAIN'] || 'example.com' %>"
    password: "<%= ENV['SMTP_PASSWORD'] %>"
    port: <%= ENV['SMTP_PORT'] || '25' %>
    user_name: "<%= ENV['SMTP_USER_NAME'] %>"

development:
  <<: *shared

test:
  <<: *shared

production:
  <<: *shared

In the Satorix Dashboard you would supply the values to be used by your production and staging environments for SECRET_KEY_BASE, SMTP_ADDRESS, SMTP_DOMAIN, SMTP_PASSWORD, SMTP_PORT, and SMTP_USER_NAME.