GUIDE_CONFIG.md

Advanced Guide: Configuring a Podium Podlet Server

This advanced guide will walk you through configuring your Podium podlet server using the config system. This guide assumes you have completed the beginner's guide and are familiar with the basics of creating a Podium podlet server.

A note on environment variables

HOST and ENV

Podlet server makes use of 2 core environment variables. HOST and ENV. Configuration in particular hangs off these values.

HOST

This is the host where the app is currently running. It's relatively freeform and podlet-server only really expects it to be a string. If HOST is not set, it will automatically be set to the value "localhost". We recommend you set this to different values for your staging and production environments. For example " staging.mysite.com" and "www.mysite.com" make good values. Whatever you set these to will affect what names you will need to give your configuration files. See below.

ENV

This is the environment mode for the podlet server. If this value is not set, it will default to "local" and whenever the app ENV is local, development features such as file watching and reloading will be enabled. Podlet server won't enable development features if ENV is set to any other value than "local" and you can feel free to set this value to whatever best suits your setup. At Finn.no we use the values "local" for local development, "dev" for our staging environment and "prod" for our production environment but you could just use "local" and "production" if that suited you better. Whatever you choose will affect how you will need to name your configuration files. See below.

Why we use ENV and not NODE_ENV

NODE_ENV is an environment popularised by the Express js framework and as such it comes with typical expectations by many developers and libraries about how it should behave. The general convention is that it be set to either development or production. Configuration in a podlet-server on the other hand is centered around a more granular environment setup usually. local, staging and production or some variation upon this.

Step 1: Create a config directory

In your project directory, create a new folder named config:

mkdir config

Step 2: Create a common configuration file

Create a new file called common.json inside the config folder:

touch config/common.json

Open common.json in your text editor and add global configuration overrides. For example, if you want to change the app name:

{
  "app": {
    "name": "my-advanced-podlet"
  }
}

Step 3: Create host/environment-specific configuration files

Inside the config folder, create a new folder named hosts:

mkdir config/hosts

hosts folders should correspond to whatever values you plan to use for your HOST environment variable.

config/hosts/<HOST>

Now, create folders for each host you want to configure. For example, if you have a localhost and a production host:

mkdir config/hosts/localhost
mkdir config/hosts/www.example.com

config files names must correspond to values you plan to use for your ENV variable:

config/hosts/<HOST>/<ENV>.json

Inside each host folder, create environment-specific configuration files. For example, for a localhost host with local, staging, and production environments:

touch config/hosts/localhost/local.json
touch config/hosts/localhost/staging.json
touch config/hosts/localhost/production.json

And for the www.example.com host:

touch config/hosts/www.example.com/local.json
touch config/hosts/www.example.com/staging.json
touch config/hosts/www.example.com/production.json

In each config file, override configuration values for the specific host and environment. For example, you can change the app.port for the local environment of the localhost host:

// config/hosts/localhost/local.json
{
  "app": {
    "port": 8081
  }
}

Step 4 Create a schema file for custom configuration values

If you need to extend the built-in config values with your own custom values, create a new file called schema.js inside the config folder:

touch config/schema.js

Open schema.js in your text editor and define your custom configuration values. For example:

export default ({ cwd, development }) => {
  db: {
    host: {
      doc: "Database host name/IP",
      format: "*",
      default: "server1.dev.test",
    },
    name: {
      doc: "Database name",
      format: String,
      default: "users",
    },
  },
};

Once you've defined your custom values in the schema file, you can override them in the common.json and host/environment-specific config files.

Step 5: Set environment variables for hosts and environments

Set the HOST and ENV environment variables when starting your app to specify the host and environment you want to use. For example:

HOST=www.example.com ENV=staging npm run start

This will use the configuration values specified in config/hosts/www.example.com/config.staging.json.

Now, you have successfully configured your Podium podlet server using the config system. You can further customize and extend your podlet server using the various features and configurations available in the Podium podlet server package.