ping 🏓

Easily ping (wake) an idle Heroku App from slumber.

Why? 🤷

We have several demo/example/tutorial Apps deployed in services like Heroku or Fly.io. In some of these (and other) services, on their "free" tier, apps go to sleep after a period of inactivity.

see:

• https://devcenter.heroku.com/articles/free-dyno-hours
• https://fly.io/docs/apps/autostart-stop/

In order to wake them, we wrote a few lines of code that can be added to any Elixir/Phoenix App and invoked as an image in the README.md of the project that links to the App. So the app is ready to go by the time the person reading the README.md clicks on the link. 🔗

We had implemented the "wake from sleep" endpoint several times in our Apps (e.g. see dwyl/email)

After copy-pasting the code a couple of times, we decided to make it a DRY reusable package that we can use in our next app(s)!

What? 💡

An easy way for us to wake our Elixir apps when deployed in cloud services like Fly.io.

Particularly useful when you want to pre-emptively wake your suspended/sleeping/inactive deployed application when people read your project's README.

Who? 👤

This package is for anyone building an Elixir/Phoenix app that is deployed in services that allow you to run full-stack applications like Fly.io.

How? 💻

Add ping to your Phoenix App and use it to wake your App in 4 easy steps:

1. Installation 📝

Install by adding ping to your list of dependencies in mix.exs:

def deps do
  [
    {:ping, "~> 1.1.0"},
  ]
end

e.g: mix.exs#L61

2. Create a get /ping Route in your router.ex

Open the router.ex file of your Phoenix project and add the following route to your default pipeline:

get "/ping", PingController, :ping

e.g: lib/app_web/router.ex#L21

3. Create the ping/2 Function in your Controller

defmodule AppWeb.PingController do
  use AppWeb, :controller

  # see: github.com/dwyl/ping
  def ping(conn, params) do
    Ping.render_pixel(conn, params)
  end
end

e.g: lib/app_web/controllers/ping_controller.ex#L5-L7

You can either create a brand new controller, or use an existing one if you prefer.
We've created a new controller for clarity/separation.

3.b Create the Corresponding Test (Optional+Recommended)

Create the corresponding test file to keep your Test coverage complete:

defmodule AppWeb.PingControllerTest do
  use AppWeb.ConnCase

  test "GET /ping (GIF) renders 1x1 pixel", %{conn: conn} do
    conn = get(conn, Routes.ping_path(conn, :ping))
    assert conn.status == 200
    assert conn.state == :sent
    assert conn.resp_body =~ <<71, 73, 70, 56, 57>>
  end
end

e.g: test/app_web/controllers/ping_controller_test.exs#L5-L10

4. Add a GIF to the README.md of the App

Add an image linking to the endpoint of the App to the README.md file:

![wake-sleeping-heroku-app](https://phxtodo.herokuapp.com/ping)

e.g: pull/5/files

The GIF is a transparent 1x1 pixel, so it's both minimal in size to minimise response time and invisible to the person. The idea is just to make the most basic HTTP request to the app in order to wake it. We don't actually care what is returned. But we don't want it to 404 so the person reading the README.md doesn't see an error in their console/browser.

Docs available at https://hexdocs.pm/ping. But there's really not much to it.