Documentation

[bitwalker]

Documentation

[lee-reinhardt]

I want to say thank you for giving umbrella apps first-class consideration here. We use them frequently, and while we have releases working with exrm it was a bit of trial and error :)

[LevelbossMike]

@matteosister You can create a post_start-hook and execute that whenever the application starts up:

#rel/hooks/post_start
sleep 1 # ensure node is up
echo "Running migrations"
bin/plug_test rpc Elixir.Release.Task migrate
echo "Migrations run successfully"

You can create that Release.Task in lib:

defmodule Release.Tasks do
  def migrate do
    {:ok, _} = Application.ensure_all_started(:my_app)

    path = Application.app_dir(:my_app, "priv/repo/migrations")

    Ecto.Migrator.run(MyApp.Repo, path, :up, all: true)
  end
end

via http://blog.plataformatec.com.br/2016/04/running-migration-in-an-exrm-release/

and in rel/config.exs

#...
environment :prod do
  set include_erts: true
  set include_src: false

  set post_start_hook: "rel/hooks/post_start"
end
#...

via # https://elixirforum.com/t/deploy-sometimes-complaining-about-node-not-running/1232/3

[gabrie30]

@supernullset any progress on the migration documentation? Running migrations after a deploy is pretty common, but not well documented. Even adding @LevelbossMike blog post in the readme would be a step in the right direction.

[bitwalker]

@matteosister you should be able to just run nodetool ping instead of ERL_EPMD_PORT=40006 bin/my_app ping, since they ultimately do the same thing, and you can avoid having to set the epmd port (I wouldn't expect you to have to do that anyway, but I suppose there might be conflicts when running the boot script from within the boot script environment).

[supernullset]

@bitwalker My thinking is that I extend the application which I use for the phoenix walkthrough with some generated models and cover the post_start hook within a Phoenix context. I would pretty much like to add the solution proposed by @LevelbossMike and yourself (nodetool ping) to a document with a digestible explanation. Additionally, I would like to cover adding a migration rollback script controlled by a conditional env var, example:

if [ ${ROLLBACK} ]
then
   echo "ROLLBACK"
fi

Im digging around through a bunch of Erlang material on releases to see if I cannot find a cleaner way to do this. I unfortunately can only read so much at a time!

[bitwalker]

@lee-reinhardt For sure, I've started to use umbrellas for a few things, and it was a pain point for me as well, so I made them a priority this time around :)

[supernullset]

@bitwalker I would be happy to help with Walkthrough of a complete end-to-end deployment/upgrade of a Phoenix application, with modified assets As its something that I need to do for a personal project. If you would like the help, I am going to be moving my project from exrm to distillery. Is it worth breaking this out into another issue to discuss what you would like for the documentation to reflect/focus on as well as other details (where this doc will live etc)?

[bitwalker]

@supernullset That's awesome! Thanks for offering! Feel free to break it out into a separate issue, I'm using this one as more of a general umbrella under which documentation things can be tracked, but for individual tasks it might get a bit noisy.

Things to keep in mind/general advice:

• I'd like it to be a reflection of common needs in Phoenix, one of the big ones is handling updated assets (js/css/etc.), and making sure that when you flip the switch on the upgrade, that the new assets are being served, and not the old ones, websocket connections are held open, etc.
• Depending on how you feel about it, I'd recommend also upgrading cowboy as part of the upgrade portion of the guide, since historically there were issues there, and seeing that it works will help build confidence in that capability. Probably the best way to do that is to pin the initial version of cowboy in the project at the last minor version, then upgrade it later. It's somewhat artificial, but gets the point across I think.
• All raw docs are written in Markdown and stored in the docs folder in the project root, and I add them to mix.exs when they are ready to go live on hexdocs.pm.
• Make use of other documentation pages (i.e. link out to them) when referencing specifics, except where those things diverge from other documentation. That way the maintenance burden is significantly less when changes occur.
• I'll let you be the driver on what you think the flow and focus of the guide should be, since you're coming at it fresh, and I think that perspective is important. If I have critiques, I'll follow up in the PR for the new guide, but for now, just go with your gut :)
• Be descriptive as possible, try not to assume anything about the knowledge of the people coming to the guide. In my experience, any assumptions made will almost certainly result in issues being opened later on due to confusion for beginners. The only safe assumptions are that if you put something in the guide, then they have read it, though even that is never a guarantee, but we're setting that expectation ;).
• If something is important, call it out with italics/bold as much as possible, when guides get lengthy, it can become easy to overlook important steps if you aren't careful.

Ping me with any questions!

[supernullset]

@bitwalker Much obliged! I'll get started and check in with you as needed. I'm aiming for Monday 15th for a first draft. I want to have some time for feedback before Elixirconf!

[matteosister]

@bitwalker we are currently using distillery to deploy to our infrastructure. It would be really great if you could just give us some hint about calling mix tasks in "compiled" environment. We need to execute "ecto.migrate"

[matteosister]

@LevelbossMike many thanks for the advice!!! Works great. We find that the sleep 1 was not reliable on our servers. So we ended up with this

set +e
set -x

while true; do
  ERL_EPMD_PORT=40006 bin/my_app ping
  EXIT_CODE=$?
  if [ $EXIT_CODE -eq 0 ]; then
    echo "Application is up!"
    break
  fi
done

set -e
set +x

echo "Running migrations"
bin/my_app rpc Elixir.Release.Task migrate
echo "Migrations run successfully"

Thanks again!

[supernullset]

@bitwalker mind if I take on the Ecto migrations documentation? I figure I have a setup for it already.

[bitwalker]

@supernullset Go for it :), could you perhaps outline what your approach is for it? I'd like to see if it's the way we should plan on doing that moving forward, or if there are improvements I can make to solve it better.

[bitwalker]

I'll save you the time of reading through the Erlang manual around releases, there is really only one good way, and that's via the apply appup instruction. It allows us to execute an MFA during the upgrade or downgrade process. It is not general across releases though (i.e. if you aren't using hot upgrades/downgrades, then the approach does not work of course), but in this particular walkthrough I think it applies.

I'm going to make a note though that I need to add a task for generating the appups seperately, so that they can be edited, and then used for assembly of the release, currently you need to extract the tarball, modify the appup, and then re-tar the release.

[supernullset]

@bitwalker Great, thanks for that info! I'll start work shortly.

[lessless]

Wow, this thread is a gem! Thanks for all the hard work you're doing here guys - my Friday morning just become better ❤️