Skip to main content
Version: 2.13.0

Using Environment Variables with Platformatic

Applications built with Platformatic loosely follows the twelve factor app methodology. This guide will show how to make your application configurable, while keeping your deployment environments as close as possible.

Environment Variables replacement​

In any Platformatic configuration file, you can always interpolate an environment variable inside a value:

{
  ...
  "db": {
    "connectionString": "{DATABASE_URL}"
  }
  ...
}

The replacement is done via pupa, after the JSON file is parsed.

All Platformatic configuration files support Environment Variables replacement, i.e. env variables are supported in Platformatic Service, Platformatic DB, Platformatic Composer, Platformatic Runtime.

dotenv support​

dotenv is built in inside Platformatic, allowing you to create an envfile with all your environment variables, that is loaded automatically by Platformatic at startup. If a .env file exists it will automatically be loaded by Platformatic using dotenv. For example:

.env
DATABASE_URL=sqlite://./db.sqlite

The .env file must be located in the same folder as the Platformatic configuration file or in the current working directory.

Environment variables can also be set directly on the command line, for example:

PLT_SERVER_LOGGER_LEVEL=debug npx platformatic start

Adding a custom environment variable to a project​

Create a Platformatic DB App​

To start the Platformatic creator wizard, run the appropriate command for your package manager in your terminal:

npm create platformatic@latest

This interactive command-line tool will guide you through setting up a new Platformatic project. For this guide, please choose the following options:

- Where would you like to create your project?  => quick-start
- Which kind of project do you want to create?  => @platformatic/db
- What is the name of the service?              => (generated-randomly), e.g. legal-soup
- What is the connection string?                => sqlite://./db.sqlite
- Do you want to create default migrations?     => Yes
- Do you want to create another service?        => No
- Do you want to use TypeScript?                => No
- What port do you want to use?                 => 3042
- Do you want to init the git repository?       => No

After completing the wizard, your Platformatic application will be ready in the quick-start folder. This includes example migration files, plugin scripts, routes, and tests within your service directory.

note

If the wizard does not handle dependency installation, ensure to run npm/yarn/pnpm install command manually:

This same tutorial applies to all other Platformatic tools.

Modify platformatic.db.json​

Add a greeting option inside your plugins configuration:

{
  ...
  "plugins": {
    "paths": [
      {
        "path": "./plugins",
        "encapsulate": false,
        "options": {
          "greeting": "{PLT_GREETING}"
        }
      },
      {
        "path": "./routes"
      }
    ]
  },
  ...
}

This new options will be available inside all the options passed to all plugins in the plugins/ folder.

Decorate the Fastify instance​

Create a new plugins/greeting.js file, calling fastify.decorate() to expose some functionality to other plugins:

/// <reference path="../global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} fastify */
module.exports = async function (fastify, opts) {
  fastify.decorate('sayHello', sayHello)

  function sayHello (name) {
    return `${opts.greeting} ${name}`
  }
}

Use it inside a route​

Create a new routes/hello.js file that uses the newly added functionality, like so:

/// <reference path="../global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} fastify */
module.exports = async function (fastify, opts) {
  fastify.get('/hello', {
    schema: {
      querystring: {
        type: 'object',
        properties: {
          name: { type: 'string' }
        }
      },
      required: ['name']
    }
  }, async (request, reply) => {
    return fastify.sayHello(request.query.name)
  })
}

Add an environemnt variable​

Edit your .env file and add:

PLT_GREETING=Hello

Don't forget to add a default value to your .env.sample, as the .env file is not committed to the repository.

Run your application and test the new route​

Run your application with npm start, and then test the new route with:

curl 'http://localhost:3042/hello?name=matteo'