Configuration

Convoy can be configured by using one of or a combination of the methods below:

1. Creating a convoy.json configuration file (default)
2. Setting environment variables.
3. Setting CLI flags

The order of preference when all three is used is CLI flags > environment variables > convoy.json file. Values set in the cli flags will override the same config value set with either env vars of in the config file.

Configuration File

An example configuration is shown below:

{
  "host": "hooks.domain.com",
  "database": {
      "host": "localhost",
      "username": "postgres",
      "password": "postgres",
      "database": "convoy",
      "options": "sslmode=disable&connect_timeout=30",
      "port": 5432
  },
  "server": {
      "http": {
          "ssl": false,
          "ssl_cert_file": "",
          "ssl_key_file": "",
          "port": 5005,
          "worker_port": 5006
      }
  },
  "redis": {
      "port": 6379,
      "host": "localhost"
  },
  "search": {
      "type": "typesense",
      "typesense": {
          "host": "http://typesense:8108",
          "api_key": "convoy"
      }
  }
}

Parameters

This section explains the role of the parameters used in configuring the Convoy instance.

1. database ( required ) <br /> The parameter houses the configuration for the main data store. Currently supported databases: PostgreSQL.

   {
     "database": {
       "host": "localhost",
       "username": "postgres",
       "password": "postgres",
       "database": "convoy",
       "options": "sslmode=disable&connect_timeout=30",
       "port": 5432
     }
   }
   

2. redis <br /> These parameters are used to configure convoy's queuing backend, caching backend and rate limiting backend respectively.

   {
       "redis": {
         "port": 6379,
         "host": "localhost"
       }
   }
   

3. server ( optional ) <br /> This parameter configures the settings for both the api and worker server. It specifies the port and ssl settings for the both the api and worker server. ssl defaults to false, when set ssl_key_file and ssl_cert_file must be set as well. port and worker_port are set to 5005 and 5006 by default respectively.

4. auth ( required ) <br /> This specifies the authentication mechanism used to access Convoy's API. Convoy has two APIs; one for the UI and the other for the public API. Each API requires authentication by default. Convoy supports two authentication mechanisms: <br />

   1. native: Configure realm. This is used for the Public API.
   2. jwt: Configure jwt. This is used for UI authentication.

   {
     "auth": {
       "native": {
         "enabled": true
       },
       "jwt": {
         "enabled": true
       },
     }
   }
   

5. smtp ( optional ) <br /> Convoy sends out emails for several reasons for dead endpoints, team invitation etc. It needs a SMTP provider to do this.

   {
       "smtp": {
   		"provider": "sendgrid",
   		"url": "smtp.sendgrid.net",
   		"port": 2525,
   		"username": "apikey",
   		"password": "api-key-from-sendgrid",
   		"from": "[email protected]"
   	}
   }
   

6. host ( optional ) <br /> This specifies your convoy instance host name. It is used for various things like portal link configuration, user invitation.

Environment Variables

Alternatively, you can configure Convoy using the following environment variables: