Questions about structuring code, contexts, umbrellas and deployment


Some general info first. I am starting on a new project, to be deployed in a docker swarm. I already played with phoenix, but just when I got used to it a bit, 1.3 came out, and throws me off track. Also I feel like I am continuously needing to research a lot (even to keep up with things) and cannot actually start because of that.

I’ve looked at a few videos on 1.3, contexts, umbrellas, and read some discussions about them, but these only left me more confused. So I decided to just go look for advice from the community.

My application involves two public websites, a few internal (admin) sties, one public API with Oauth2, and a few internal APIs (only reachable inside the swarm). microservices if you will.

Now my questions are about structuring code and directories, umbrellas and deployment. Looking for best practices, and not: ‘anything is possible, depending on how you want to structure it’ answers.


Looking at my use case, should I create an umbrella project and create separate apps for each website, and each api?

Can apps inside an umbrella project be deployed separately? Can they be deployed together? Are there recipes for that, or do I (again) need to research it? If I deploy containers, should I deploy the entire umbrella project into every container and just activate the application I need to use for that container? Or create separate containers for each app.

I’ve seen two ways to create umbrella projects, mix xxx --umbrella and mix new xxx --umbrella . They differ greatly in files generated. Which one would be best in my case?

Examples on the net mention --sup to generate a supervisor tree. Would that be useful in my case?

Can I even host multiple websites on one Phoenix instance? If so how?

Can I directly call into another application in the same umbrella (is the code living in the same root namespace) or do I need to consume the API it publishes?

Thanks for any insights,
– Ron

These are two different things:

mix new xxx --umbrella

will generate an umbrella project for you. You put any of your Elixir apps into it’s apps/ subdirectory. This is where the other task comes in handy:

cd xxx/apps
mix xxx --umbrella

this will generate you Phoenix application in a way that it suits best being part of umbrella project.

So you mention the third generator with ---sup option: you would use it if you wanted to generate 2nd application inside your umbrella project, like a backend application or “core” or whatever you call it. If you in this application would want to start supervision tree of sorts (like Ecto), you would most likely use --sup option.

So I would use mix xxx --umbrella if the new app is part of an umbrella? I just ran this while not being inside an umbrella, and it did not complain/warn.

If you in this application would want to start supervision tree of sorts (like Ecto), you would most likely use --sup option.

In what cases would I want to start a supervision tree?

Okay, I lied to you. I am sorry.

I just ran the new mix --umbrella foo generator and what it did was:

  1. Created a foo_umbrella project
  2. Created a foo application inside umbrella’s app. This foo application contains supervision tree where Ecto is mounted (look into application.ex)
  3. Created a foo_web application that contains only phoenix app.

I think it’s very handy generator as it saves you some time and gives nice architecture out of the box. You could do it by hand, however by generating main project with mix new --umbrella foo_umbrella, then generating the foo app with --sup option, adding Ecto by hand to this foo app and mounting it’s supervisor in application.ex. Then you would generate foo_web app, with --no-ecto, since you would use repo and models from foo.

1 Like