How do I exit the BEAM VM with exit code 0 on top-level supervisor auto-shutdown?

Questions / Help
, , ,
1

Hi Elixir community :blush:

I’m having some trouble getting the BEAM VM to exit with exit code 0 upon auto-shutdown of the top-level supervisor.

For context, I’m writing an application that runs a cron job in cloud environment in a Docker container. So periodically, the cloud environment starts the container, which starts up my application, which runs a function to do some stuff. After that function exits (without raising), I want my application to exit and subsequently, I want the container to exit with exit code 0, so that the cloud environment knows that the run was successful.

Here’s my application module:

defmodule OpiniLead.Scrape.Application do
  @moduledoc """
  The application module for `OpiniLead.Scrape`.
  """
  use Task, significant: true
  use Application

  def start_link(_) do
    scrapers = Application.fetch_env!(:opinilead, :scrapers)
    Task.start_link(OpiniLead.Scrape, :run, [scrapers])
  end

  def start(_type, _args) do
    Supervisor.start_link([__MODULE__],
      strategy: :one_for_one,
      auto_shutdown: :all_significant,
      name: OpiniLead.Scrape.Supervisor
    )
  end
end

When I start this application, the task runs successfully and the supervisor exits with reason :shutdown, as expected. However, the BEAM VM seems to interpret this as a crash and exits with error code 1:

{"message":"Application opinilead exited: shutdown","@timestamp":"2025-03-03T10:56:46.693Z","ecs.version":"8.11.0","log.level":"notice","log.logger":"application_controller","log.origin":{"function":"info_exited/3","file.line":2125,"file.name":"application_controller.erl"}}
Kernel pid terminated (application_controller) ("{application_terminated,opinilead,shutdown}")

Crash dump is being written to: erl_crash.dump...done

How do I let the BEAM VM interpret :shutdown as a normal / successful exit reason so it exits without a crash (and with exit code 0)? Or should I use an entirely different approach to release a Docker image that just runs a function until completion and then exits?

Note: I’m currently using mix releases to build my application into an executable for the Docker image, which is then started with bin/opinilead start. I also have a few tests which call Application.start(:opinilead) and then verify that the supervisor starts, runs and exits, which prevents me from straight-up calling System.stop(0) in the application’s stop/1 callback.

2

I would use the System.stop function to shut down the node on completion.

2 Likes
3

Yeah, even a normal shutdown for a top level supervisor is an abnormal behaviour as a permanent application is not meant to have its top level supervisor exit. Even a :transient application only allows for :normal exit reason, not :shutdown.

1 Like
4

Hmmmm okay yeah I was afraid of that. It still feels wrong to use System.stop in an application, it might be a good indication that applications are not the right abstraction for releasing a Docker image that runs such one-off tasks.

I found a different solution though, one that might be a bit cleaner. Simply put: use eval instead of start.

My application module now looks as follows:

defmodule OpiniLead.Scrape.Application do
  @moduledoc """
  A pseudo-application module for `OpiniLead.Scrape`.
  Usually, an Application's `start/2` callback would start a supervisor that manages a permanently
  running system. However, in this case, we want to start a one-off task, so we define a `run` function
  that can be 'eval'ed to run the scraping as a one-off task,
  e.g. `mix run -e 'OpiniLead.Scrape.Application.run()'`.
  """

  def run do
    Application.ensure_all_started(:opinilead)
    Application.fetch_env!(:opinilead, :scrapers) |> OpiniLead.Scrape.run()
  end
end

I’ve also removed the mod key from the application callback in my mix.exs file.

I can then use mix run -e 'OpiniLead.Scrape.Application.run()' to run my one-off task in development mode. For the released Docker image, I set the command to bin/opinilead eval 'OpiniLead.Scrape.Application.run()'

With that, my app runs properly, exits with exit code 0 on success and crashes neatly when fatal errors are raised.

1 Like
5

Application.ensure_all_started(:opinilead) should do all fo that for you.

1 Like
6

Ahhh yes that works indeed and is much simpler, thanks! I’ve updated my solution accordingly :slight_smile: