Installation

Requirements

Usher requires:

• Elixir 1.14 or later
• OTP 25 or later
• PostgreSQL

Note: Usher may work with earlier versions of Elixir and OTP, but it wasn't tested against them.

Adding Usher to Your Project

Add usher to your list of dependencies in mix.exs:

def deps do
  [
    {:usher, "~> 0.1.0"}
  ]
end

Then run:

mix deps.get

Database Setup

Usher requires database tables to store invitation data. You'll need to create and run a migration to set up these tables.

1. Configuring the JSON library

Ecto requires a JSON library for encoding and decoding JSON data. While this is optional, Usher requires it due to custom Ecto types.

If you're on Elixir 1.18 or later, you can use the built-in Elixir.JSON module, like so:

config :postgrex, json_library: Elixir.JSON

Otherwise, you can use Jason as your JSON library. Add it to your dependencies:

def deps do
  [
    {:usher, "~> 0.1.0"},
    {:jason, "~> 1.4"}
  ]
end

⚠️ if you change the json_library configuration, make sure to recompile the Postgrex adapter. Otherwise your change won't be picked up:

mix deps.clean --build postgrex

2. Generate Migration

Create a new migration file:

mix ecto.gen.migration install_usher_tables

3. Add Migration Content

Add the Usher schema to your migration file:

defmodule MyApp.Repo.Migrations.InstallUsherTables do
  use Ecto.Migration

  def change do
    Usher.Migration.migrate_to_version("v03")
  end
end

4. Run Migration

Execute the migration:

mix ecto.migrate

This will create the necessary tables for storing invitations and tracking their usage.

ℹ️ Pass in the Usher.Migration.latest_version/0 value to Usher.Migration.migrate_to_version/1 to apply only the necessary migrations.

Next Steps

After installation, you'll need to configure Usher for your application. See the Getting Started Guide for configuration and basic usage examples.