Migration guide from 2.0.x to 2.1.0

Please note that for standard usage, when configuring MongoosePush only with environmental variables, the config/*.exs files are upgraded automatically and there is no action required from your end. If your MongoosePush is using modified config/*.exs files, please have a closer look at the changes presented below to see if you have to adjust your custom configuration. In such case, there could be a few changes necessary in the configuration files and a few additional, optional ones.

Main config (config/config.exs)

MongoosePush supports structured logging from the 2.1.0 release. To use that feature, there is a need to change the logger configuration to use the new default. Old logger config:

config :logger, :console,
  format: "\n$dateT$time [$level] $metadata$levelpad$message\n",
  metadata: [:pid]

New logger config:

config :logger, :console,
  format: {MongoosePush.Logger.LogFmt, :format},
  metadata: :all

Further notes on logging are in the logging section

Additionally there are a few new defaults needed to be set up:

config :mongoose_push, MongoosePush.Service,
  fcm: MongoosePush.Service.FCM,
  apns: MongoosePush.Service.APNS

config :mongoose_push, backend_module: MongoosePush

config :phoenix, :json_library, Jason

Lastly, since 2.1.0 MongoosePush uses Phoenix instead of Maru and Maru config entry can be removed.

config :maru, :test, false

Environmental configs (config/{prod|dev|test}.exs)

Phoenix in place of Maru

As mentioned earlier, MongoosePush uses Phoenix and the config has to be updated to reflect that change. Old Maru config entry:

config :maru, MongoosePush.Router,
  versioning: [
    using: :path
  ],
  https: [
    bind_addr: {:system, :string, "PUSH_HTTPS_BIND_ADDR", "127.0.0.1"},
    port: {:system, :integer, "PUSH_HTTPS_PORT", 8443},
    keyfile: {:system, :string, "PUSH_HTTPS_KEYFILE", "priv/ssl/fake_key.pem"},
    certfile: {:system, :string, "PUSH_HTTPS_CERTFILE", "priv/ssl/fake_cert.pem"},
    cacertfile: {:system, :string, "PUSH_HTTPS_CERTFILE", "priv/ssl/fake_cert.pem"},
    acceptors: {:system, :integer, "PUSH_HTTPS_ACCEPTORS", 100},
    otp_app: :mongoose_push
  ]

It should be removed completely and in its place there must be the new, Phoenix config entry:

config :mongoose_push, MongoosePushWeb.Endpoint,
  https: [
    ip: {
      :system,
      # Custom type parser (Phoenix needs erlang-inet-style IP address)
      {MongoosePush.Config.Utils, :parse_bind_addr, []},
      "PUSH_HTTPS_BIND_ADDR",
      {127, 0, 0, 1}
    },
    port: {:system, :integer, "PUSH_HTTPS_PORT", 8443},
    keyfile: {:system, :string, "PUSH_HTTPS_KEYFILE", "priv/ssl/fake_key.pem"},
    certfile: {:system, :string, "PUSH_HTTPS_CERTFILE", "priv/ssl/fake_cert.pem"},
    cacertfile: {:system, :string, "PUSH_HTTPS_CERTFILE", "priv/ssl/fake_cert.pem"},
    protocol_options: [
      # https://ninenines.eu/docs/en/cowboy/2.5/manual/cowboy_http/
    ],
    transport_options: [
      # https://ninenines.eu/docs/en/ranch/1.6/manual/ranch_tcp/
      # https://ninenines.eu/docs/en/ranch/1.6/manual/ranch_ssl/
      num_acceptors: {:system, :integer, "PUSH_HTTPS_ACCEPTORS", 100}
    ],
    otp_app: :mongoose_push
  ],
  debug_errors: false,
  code_reloader: false,
  check_origin: true,
  server: true

As you can see, there is no change in the variables used to parse the options.

Logging

Old logging entry looked like this:

config :mongoose_push, loglevel: {:system, :atom, "PUSH_LOGLEVEL", :info}

New logging entry may look like the following:

config :mongoose_push, :logging,
  level: {:system, :atom, "PUSH_LOGLEVEL", :info},
  format: {:system, :atom, "PUSH_LOGFORMAT", :json}

The structure changed a little and there is a new variable, PUSH_LOGFORMAT. It defaults to :json for the prod environment, and to :logfmt for the dev and test environments. The logfmt backend was changed to support structured logging. Please note that if you had a MongoosePush node configured with a log aggregation backend it probably needs to be reconfigured to match the current format of the log messages. You might also want to consider using the second standard, JSON, that MongoosePush now supports.

OpenAPI

MongoosePush can expose OpenAPI specification if enabled. Config entry may look like this:

config :mongoose_push,
  openapi: [
    expose_spec: {:system, :boolean, "PUSH_OPENAPI_EXPOSE_SPEC", false},
    expose_ui: {:system, :boolean, "PUSH_OPENAPI_EXPOSE_UI", false}
  ]

PUSH_OPENAPI_EXPOSE_SPEC enables OpenAPI endpoint support and PUSH_OPENAPI_EXPOSE_UI enables SwaggerUI. Both these options are disabled by default. For more details refer to the configuration guide.

Elixometer

MongoosePush does not use Elixometer for its metrics anymore. Metrics are provided using Telemetry and elixometer config entry should be removed. Old elixometer entry:

config :elixometer,
  reporter: :exometer_report_tty,
  env: Mix.env(),
  metric_prefix: "mongoose_push"

There is no config entry necessary for Telemetry metrics. To learn more about the new metrics and see how to setup default Grafana dashboards check out the metrics guide.

API

Please note that API v2 is deprecated and will be removed in the future. API v2 and v3 differ only by the returned status and content in case of errors, so in case you are using API v2 please consider changing to API v3.