Skip to content
You are reading Codefi Orchestrate development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Configure Orchestrate Gateway API

Follow these steps to configure and connect to Orchestrate Gateway API dependencies:

  1. Configure PostgreSQL database (mandatory)
  2. Configure Apache Kafka (mandatory)
  3. Configure monitoring (optional). Improve the development experience and debugging.
  4. Configure Multi-tenancy (optional). Use Orchestrate with multiple tenants.
  5. Configure the Chain Proxy cache (optional).

In addition to the dependencies, Orchestrate Gateway API needs to be configured to connect to the other microservices and to define how the service should be exposed.

Tip

Configure each microservice using microservice-specific environment variables. Command line options are also available and take precedence over environment variables.

Configuration

Environment Variable Command line option Description Default
REST_HOSTNAME rest-hostname Hostname to expose REST services
REST_PORT rest-port Port to expose REST services 8081
KEY_MANAGER_URL key-manager-url URL of the Key Manager HTTP endpoint http://localhost:8081
KEY_MANAGER_METRICS_URL (only ENV var) URL of the Key Manager HTTP metrics endpoint http://localhost:8082

CLI options

See the complete list of command line options for the Orchestrate Gateway API:

Run options

Usage:
  orchestrate api run [flags]

Flags:
      --db-database string                                 Target Database name
                                                           Environment variable: "DB_DATABASE" (default "postgres")
      --db-host string                                     Database host
                                                           Environment variable: "DB_HOST" (default "127.0.0.1")
      --db-keepalive duration                              Controls the number of seconds after which a TCP keepalive message should be sent
                                                           Environment variable: "DB_KEEPALIVE" (default 1m0s)
      --db-password string                                 Database User password
                                                           Environment variable: "DB_PASSWORD" (default "postgres")
      --db-poolsize int                                    Maximum number of connections on database
                                                           Environment variable: "DB_POOLSIZE"
      --db-port int                                        Database port
                                                           Environment variable: "DB_PORT" (default 5432)
      --db-sslmode string                                  TLS/SSL mode to connect to database (one of "DB_TLS_SSLMODE")
                                                           Environment variable: ["require" "disable" "verify-ca" "verify-full"] (default "disable")
      --db-tls-ca string                                   Trusted Certificate Authority
                                                           Environment variable: "DB_TLS_CA"
      --db-tls-cert string                                 TLS Certificate to connect to database
                                                           Environment variable: "DB_TLS_CERT"
      --db-tls-key string                                  TLS Private Key to connect to database
                                                           Environment variable: "DB_TLS_KEY"
      --db-user string                                     Database User.
                                                           Environment variable: "DB_USER" (default "postgres")
  -h, --help                                               help for run
      --kafka-consumer-group-heartbeat-interval duration   The expected time between heartbeats to the consumer coordinator when using Kafka's
                                                           group management facilities. Heartbeats are used to ensure that the consumer's session stays active and to facilitate rebalancing when new consumers join or leave the group.
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_HEARTBEAT_INTERVAL" in ms (default 3s)
      --kafka-consumer-group-rebalance-strategy string     Strategy for allocating topic partitions to members (one of ["RoundRobin" "Sticky" "Range"]).
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_REBALANCE_STRATEGY" (default "Range")
      --kafka-consumer-group-rebalance-timeout duration    The maximum allowed time for each worker to join the group once a rebalance has begun. This
                                                           is basically a limit on the amount of time needed for all tasks to flush any pending data and commit offsets. If the timeout is exceeded, then the worker will be removed from the group, which will cause offset commit failures
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_REBALANCE_TIMEOUT" (default 1m0s)
      --kafka-consumer-group-session-timeout duration      The timeout used to detect consumer failures when using Kafka's group management facility.
                                                           The consumer sends periodic heartbeats to indicate its liveness to the broker. If no heartbeats are received by the broker before the expiration of this session timeout, then the broker will remove this consumer from the group and initiate a rebalance.
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_SESSION_TIMEOUT" (default 10s)
      --kafka-consumer-max-processing-time duration        The maximum amount of time the consumer expects a message takes to process for the user. If
                                                           writing to the Messages channel takes longer than this, that partition will stop fetching more messages until it can proceed again.
                                                           Environment variable: "KAFKA_CONSUMER_MAXPROCESSINGTIME" (default 100ms)
      --kafka-consumer-max-wait-time duration              The maximum amount of time the broker will wait for Consumer.Fetch.Min bytes to become
                                                           available before it returns fewer than that anyways.
                                                           Environment variable: "KAFKA_CONSUMER_MAX_WAIT_TIME" in ms (default 250ms)
      --kafka-group string                                 Address of Kafka server to connect to.
                                                           Environment variable: "KAFKA_GROUP" (default "group-e2e")
      --kafka-sasl-enabled                                 Whether or not to use SASL authentication when connecting to the broker
                                                           Environment variable: "KAFKA_SASL_ENABLED"
      --kafka-sasl-handshake                               Whether or not to send the Kafka SASL handshake first if enabled (defaults to true). You
                                                           should only set this to false if you're using a non-Kafka SASL proxy.
                                                           Environment variable: "KAFKA_SASL_HANDSHAKE" (default true)
      --kafka-sasl-mechanism string                        SASLMechanism is the name of the enabled SASL mechanism. Possible values: OAUTHBEARER, PLAIN
                                                           (defaults to PLAIN).
                                                           Environment variable: "KAFKA_SASL_MECHANISM"
      --kafka-sasl-password string                         Password for SASL/PLAIN or SASL/SCRAM auth.
                                                           Environment variable: "KAFKA_SASL_PASSWORD"
      --kafka-sasl-scramauthzid string                     Authz id used for SASL/SCRAM authentication
                                                           Environment variable: "KAFKA_SASL_SCRAMAUTHZID"
      --kafka-sasl-user string                             Username for SASL/PLAIN or SASL/SCRAM auth.
                                                           Environment variable: "KAFKA_SASL_USER"
      --kafka-tls-ca-cert-file string                      CA cert file Path.
                                                           Environment variable: "KAFKA_TLS_CA_CERT_FILE"
      --kafka-tls-client-cert-file string                  Client Cert File Path.
                                                           Environment variable: "KAFKA_TLS_CLIENT_CERT_FILE"
      --kafka-tls-client-key-file string                   Client key file Path.
                                                           Environment variable: "KAFKA_TLS_CLIENT_KEY_FILE"
      --kafka-tls-enabled                                  Whether or not to use TLS when connecting to the broker (defaults to false).
                                                           Environment variable: "KAFKA_TLS_ENABLED"
      --kafka-tls-insecure-skip-verify                     Controls whether a client verifies the server's certificate chain and host name. If
                                                           InsecureSkipVerify is true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing.
                                                           Environment variable: "KAFKA_TLS_INSECURE_SKIP_VERIFY"
      --kafka-url strings                                  URL (addresses) of Kafka server(s) to connect to.
                                                           Environment variable: "KAFKA_URL" (default [localhost:9092])
      --kafka-version string                               The version of Kafka that Sarama will assume it is running against. Defaults to the oldest
                                                           supported stable version. Since Kafka provides backwards-compatibility, setting it to a version older than you have will not break anything, although it may prevent you from using the latest features. Setting it to a version greater than you are actually running may lead to random breakage.
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_REBALANCE_TIMEOUT" (default "1.0.0")
      --key-manager-url string                             URL of the Key Manager HTTP endpoint.
                                                           Environment variable: "KEY_MANAGER_URL" (default "http://localhost:8081")
      --metrics-modules strings                            List of metrics modules to exposed by prometheus endpoint. Available metric modules are
                                                           ["http" "tcp" "orchestrate_transaction_scheduler" "go" "process" "healthz"], to enable all use ENABLED or to disable all DISABLED.
                                                           Environment variable: "METRICS_MODULES" (default [ENABLED])
      --proxy-cache-ttl duration                           Proxy Cache TTL duration (Disabled by default). Environment variable: "PROXY_CACHE_TTL"
      --proxy-max-idle-connections-per-host int            Maximum number of open HTTP connections to a chain proxied. Environment variable:
                                                           "PROXY_MAXIDLECONNSPERHOST" (default 50)
      --rest-hostname string                               Hostname to expose REST services
                                                           Environment variable: "REST_HOSTNAME"
      --rest-port uint                                     Port to expose REST services
                                                           Environment variable: "REST_PORT" (default 8081)
      --topic-tx-sender string                             Kafka topic for envelopes waiting for their transaction sent
                                                           Environment variable: "TOPIC_TX_SENDER" (default "topic-tx-sender"

Migration options

Usage:
  orchestrate api migrate [flags]
  orchestrate api migrate [command]

Available Commands:
  copy-db     Copy Database from version 2.5.x to version 21.1.x
  down        Reverts last migration
  init        Initialize database
  reset       Reverts all migrations
  set-version Set database version
  up          Upgrade database
  version     Print current database version

Flags:
      --db-database string      Target Database name
                                Environment variable: "DB_DATABASE" (default "postgres")
      --db-host string          Database host
                                Environment variable: "DB_HOST" (default "127.0.0.1")
      --db-keepalive duration   Controls the number of seconds after which a TCP keepalive message should be sent
                                Environment variable: "DB_KEEPALIVE" (default 1m0s)
      --db-password string      Database User password
                                Environment variable: "DB_PASSWORD" (default "postgres")
      --db-poolsize int         Maximum number of connections on database
                                Environment variable: "DB_POOLSIZE"
      --db-port int             Database port
                                Environment variable: "DB_PORT" (default 5432)
      --db-sslmode string       TLS/SSL mode to connect to database (one of "DB_TLS_SSLMODE")
                                Environment variable: ["require" "disable" "verify-ca" "verify-full"] (default "disable")
      --db-tls-ca string        Trusted Certificate Authority
                                Environment variable: "DB_TLS_CA"
      --db-tls-cert string      TLS Certificate to connect to database
                                Environment variable: "DB_TLS_CERT"
      --db-tls-key string       TLS Private Key to connect to database
                                Environment variable: "DB_TLS_KEY"
      --db-user string          Database User.
                                Environment variable: "DB_USER" (default "postgres")
  -h, --help                    help for migrat
ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can obtain paid professional support by Consensys at orchestrate@consensys.net