Getting Started

This guide will briefly explain how to get started with using Mate. It assumes you already have an Elixir project and a build and/or deploy server that you can access via SSH.

Installation

Mate is available via https://hex.pm/packages/mate. Add mate to your dependencies in the mix.exs file, you only need it for :dev as you only use it to run locally from your machine.

def deps do
  [
    {:mate, "~> 0.1.7", only: :dev}
  ]
end

After adding this to your mix.exs file, run mix deps.get to download it and then continue.

First time configuration

All configuration will be stored in a file called .mate.exs and uses the default Config syntax from Elixir.

To get you started Mate includes a task to create your configuration file using mix mate.init. You can optionally pass it some arguments to change it for your usecase.

After running this command you should have a new .mate.exs file looking something like this:

import Config

config :mate,
  otp_app: :my_app,
  module: MyApp

# This simple configuration will build and deploy to the same server
config :staging,
  server: "example.com",
  build_path: "/tmp/mate/my_app",
  release_path: "/opt/my_app",

# Specify secret files, if they are already present on your build server.
# config :staging,
#   build_secrets: %{
#     "prod.secret.exs" => "/mnt/secrets/prod.secret.exs"
#   }

# You can specify separate servers like this:
# config :production,
#   build_server: "build.example.com",
#   deploy_server: "www.example.com"

# For `deploy_server` you can also set a list like this:
# config :production,
#   deploy_server: [
#     "www1.example.com",
#     "www2.example.com"
#   ]

The main things to configure are the server, build_path and release_path values. If needed you can also configure your secret files by linking them to files already on the build server.

It is also possible to configure a separate build_server and deploy_server, the default server command expects them both to be the same value.

Configure Mix Release

While Elixir 1.9+ supports a default mix release task, it does not by default generate a .tar.gz file. This is what is needed for Mate to easily transfer the release between your build and deploy servers. So in your projects mix.exs file please make sure you enable the :tar step.

defmodule MyProject.MixProject do
  use Mix.Project

  def project do
    [
      app: :my_project,
      ...
      releases: [
        my_project: [
          include_executables_for: [:unix],
          steps: [:assemble, :tar]
        ]
      ],
  ...

First release

Running mix mate.deploy will start the build process, based on your configuration file. What exactly happens there can be changed with custom steps. If something goes wrong Mate should return a useful error message, and if everything goes according to plan you should end up with a release tarball in your project directory.

After building your release Mate will prompt you if you want to deploy this release to the configured deploy servers, if you do this it will first copy the release tarball to all configured deploy servers, stop the current release (if any), unarchive the new release and start the new release.

What's next?

Hopefully everything worked, so what's next depends on what you want. There are some customization options available, different build strategies, all of which are described in this documentation.