Deployment

Applications built with Platformatic DB can be deployed to a hosting service in the same way as any other Node.js application. This guide covers a few things that will help smooth the path from development to production.

Running a Platformatic DB application

Make the Platformatic CLI available

To run a Platformatic DB application, the Platformatic CLI must be available in the production environment. The most straightforward way of achieving this is to install it as a project dependency. This means that when npm install (or npm ci) is run as part of your build/deployment process, the Platformatic CLI will be installed.

Define an npm run script

A number of hosting services will automatically detect if your project's package.json has a start npm run script. They will then execute the command npm start to run your application in production.

You can add platformatic db start as the command for your project's start npm run script, for example:

{
   ...
  "scripts": {
    "start": "platformatic db start",
  },
}

Server configuration

info

See the Configuration reference for all configuration settings.

Configuration with environment variables

We recommend that you use environment variable placeholders in your Platformatic DB configuration. This will allow you to configure different settings in your development and production environments.

In development you can set the environment variables via a .env file that will be automatically loaded by Platformatic DB. For example:

PORT=3042
PLT_SERVER_HOSTNAME=127.0.0.1

In production your hosting provider will typically provide their own mechanism for setting environment variables.

Configure the server port

Configure the port that the server will listen on by setting an environment variable placeholder in your Platformatic DB configuration file:

platformatic.db.json

{
  "server": {
    ...
    "port": "{PORT}"
  },
  ...
}

Listen on all network interfaces

Most hosting providers require that you configure your server to bind to all available network interfaces. To do this you must set the server hostname to 0.0.0.0.

This can be handled with an environment variable placeholder in your Platformatic DB configuration file:

platformatic.db.json

{
  "server": {
    ...
    "hostname": "{PLT_SERVER_HOSTNAME}",
  },
  ...
}

The environment variable PLT_SERVER_HOSTNAME should then be set to 0.0.0.0 in your hosting environment.

Security considerations

We recommend disabling the GraphiQL web UI in production. It can be disabled with the following configuration:

platformatic.db.json

{
  "db": {
    ...
    "graphql": {
      "graphiql": false
    }
  },
  ...
}

If you want to use this feature in development, replace the configuration values with environment variable placeholders so you can set it to true in development and false in production.

Removing the welcome page

If you want to remove the welcome page, you should register an index route.

module.exports = async function (app) {
  // removing the welcome page
  app.get('/', (req, reply) => {
    return { hello: 'world' }
  })
}

Databases

Applying migrations

If you're running a single instance of your application in production, it's best to allow Platformatic DB to automatically run migrations when the server starts is. This reduces the chance of a currently running instance using a database structure it doesn't understand while the new version is still being deployed.

SQLite

When using an SQLite database, you can ensure you don’t commit it to your Git repository by adding the SQLite database filename to your .gitignore file. The SQLite database file will be automatically generated by Platformatic DB when your application migrations are run in production.