{"__v":0,"_id":"5777c96b5b2b430e00b982bb","category":{"version":"5777c9635b2b430e00b982a5","project":"54348ec95b10711400c6c445","_id":"5777c9635b2b430e00b982a9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-18T21:59:42.796Z","from_sync":false,"order":3,"slug":"deployment","title":"Deployment"},"parentDoc":null,"project":"54348ec95b10711400c6c445","user":"5435e00ad7d8700800bbec51","version":{"__v":1,"_id":"5777c9635b2b430e00b982a5","project":"54348ec95b10711400c6c445","createdAt":"2016-07-02T14:02:11.084Z","releaseDate":"2016-07-02T14:02:11.084Z","categories":["5777c9635b2b430e00b982a6","5777c9635b2b430e00b982a7","5777c9635b2b430e00b982a8","5777c9635b2b430e00b982a9","5777c9635b2b430e00b982aa"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.2.0","version":"1.2.0"},"updates":["5491f01312d0c00b00c80d82","549b4972857a251f001f3744","5502972192f760210047c531","558871858cb9c30d00b1ef85","56819372aad86d0d00b9f252"],"next":{"pages":[],"description":""},"createdAt":"2014-12-03T22:20:12.350Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"Once we have a working application, we're ready to deploy it. If you're not quite finished with your own application, don't worry. Just follow the [Up and Running Guide](http://www.phoenixframework.org/docs/up-and-running) to create a basic application to work with.\n\nWhen preparing an application for deployment, there are three main steps:\n\n  * Handling of your application secrets\n  * Compiling your application assets\n  * Starting your server in production\n\nHow those are exactly handled depends on your deployment infrastructure. In particular, we have guides specific to [Heroku](http://www.phoenixframework.org/docs/heroku) and [an Advanced Deployment Guide](http://www.phoenixframework.org/docs/advanced-deployment) that uses Erlang style releases. In any case, this chapter provides a general overview of the deployment steps, which will be useful regardless of your infrastructure or if you want to run in production locally.\n\nLet's explore those steps above one by one.\n\n> Note: this guide assumes you are using at least Elixir v1.0.4, which brought some improvements on how applications are compiled and are optimized for the production environment\n\n## Handling of your application secrets\n\nAll Phoenix applications have data that must be kept secure, for example, the username and password for your production database, and the secret Phoenix uses to sign and encrypt important information. This data is typically kept in `config/prod.secret.exs` and by default it is not checked into your version control system.\n\nTherefore, the first step is to get this data into your production machine. Here is the template shipped with new applications:\n\n```elixir\nuse Mix.Config\n\n# In this file, we keep production configuration that\n# you likely want to automate and keep it away from\n# your version control system.\n\n# You can generate a new secret by running:\n#\n#     mix phoenix.gen.secret\nconfig :foo, Foo.Endpoint,\n  secret_key_base: \"A LONG SECRET\"\n\n# Configure your database\nconfig :foo, Foo.Repo,\n  adapter: Ecto.Adapters.Postgres,\n  username: \"postgres\",\n  password: \"postgres\",\n  database: \"foo_prod\",\n  size: 20 # The amount of database connections in the pool\n```\n\nThere are different ways to get this data into production. One option is to replace the data above by environment variables and set those environment variables in your production machine. This is the step that we follow [in the Heroku guides](http://www.phoenixframework.org/docs/heroku).\n\nAnother approach is to configure the file above and place it in your production machines apart from your code checkout, for example, at \"/var/config.prod.exs\". After doing so, you will have to import it from `config/prod.exs`. Search for the `import_config` line and replace it by the proper path:\n\n```elixir\nimport_config \"/var/config.prod.exs\"\n```\n\nWith your secret information properly secured, it is time to configure assets! Before taking this step, we need to do one bit of preparation. Since we will be readying everything for production, we need to do some setup in that environment by getting our dependencies and compiling.\n\n```console\n$ mix deps.get --only prod\n$ MIX_ENV=prod mix compile\n```\n\n## Compiling your application assets\n\nThis step is required only if you have static assets like images, javascript, stylesheets and more in your Phoenix applications. By default, Phoenix uses brunch, and that's what we are going to explore.\n\nCompilation of static assets happens in two steps:\n\n```console\n$ brunch build --production\n$ MIX_ENV=prod mix phoenix.digest\nCheck your digested files at \"priv/static\".\n```\n\nAnd that is it! The first command builds the assets and the second generates digests as well as a manifest file so Phoenix can quickly serve assets in production.\n\nKeep in mind that, if you by any chance forget to run the steps above, Phoenix will show an error message:\n\n```console\n$ PORT=4001 MIX_ENV=prod mix phoenix.server\n10:50:18.732 [info] Running MyApp.Endpoint with Cowboy on http://example.com\n10:50:18.735 [error] Could not find static manifest at \"my_app/_build/prod/lib/foo/priv/static/manifest.json\". Run \"mix phoenix.digest\" after building your static files or remove the configuration from \"config/prod.exs\".\n```\n\nThe error message is quite clear: it says Phoenix could not find a static manifest. Just run the commands above to fix it or, if you are not serving or don't care about assets at all, you can just remove the `cache_static_manifest` configuration from `config/prod.exs`.\n\n## Starting your server in production\n\nTo run Phoenix in production, we need to set the `PORT` and `MIX_ENV` environment variables when invoking `mix phoenix.server`:\n\n```console\n$ PORT=4001 MIX_ENV=prod mix phoenix.server\n10:59:19.136 [info] Running MyApp.Endpoint with Cowboy on http://example.com\n```\n\nIn case you get an error message, please read it carefully, and open up a bug report if it is still not clear how to address it.\n\nYou can also run your application inside an interactive shell:\n\n```console\n$ PORT=4001 MIX_ENV=prod iex -S mix phoenix.server\n10:59:19.136 [info] Running MyApp.Endpoint with Cowboy on http://example.com\n```\n\nOr run it detached from the iex console. This effectively daemonizes the process so it can run independently in the background:\n\n```elixir\nMIX_ENV=prod PORT=4001 elixir --detached -S mix do compile, phoenix.server\n```\n\nRunning the application in detached mode allows us to keep the application running even after we terminate the shell connection with the server.\n\n## Putting it all together\n\nThe previous sections give an overview about the main steps required to deploy your Phoenix application. In practice, you will end-up adding steps of your own as well. For example, if you are using a database, you will also want to run `mix ecto.migrate` before starting the server to ensure your database is up to date.\n\nOverall, here is a script you can use as starting point:\n\n```elixir\n# Initial setup\n$ mix deps.get --only prod\n$ MIX_ENV=prod mix compile\n\n# Compile assets\n$ brunch build --production\n$ MIX_ENV=prod mix phoenix.digest\n\n# Custom tasks (like DB migrations)\n$ MIX_ENV=prod mix ecto.migrate\n\n# Finally run the server\n$ PORT=4001 MIX_ENV=prod mix phoenix.server\n```","excerpt":"","slug":"deployment","type":"basic","title":"Introduction"}
Once we have a working application, we're ready to deploy it. If you're not quite finished with your own application, don't worry. Just follow the [Up and Running Guide](http://www.phoenixframework.org/docs/up-and-running) to create a basic application to work with. When preparing an application for deployment, there are three main steps: * Handling of your application secrets * Compiling your application assets * Starting your server in production How those are exactly handled depends on your deployment infrastructure. In particular, we have guides specific to [Heroku](http://www.phoenixframework.org/docs/heroku) and [an Advanced Deployment Guide](http://www.phoenixframework.org/docs/advanced-deployment) that uses Erlang style releases. In any case, this chapter provides a general overview of the deployment steps, which will be useful regardless of your infrastructure or if you want to run in production locally. Let's explore those steps above one by one. > Note: this guide assumes you are using at least Elixir v1.0.4, which brought some improvements on how applications are compiled and are optimized for the production environment ## Handling of your application secrets All Phoenix applications have data that must be kept secure, for example, the username and password for your production database, and the secret Phoenix uses to sign and encrypt important information. This data is typically kept in `config/prod.secret.exs` and by default it is not checked into your version control system. Therefore, the first step is to get this data into your production machine. Here is the template shipped with new applications: ```elixir use Mix.Config # In this file, we keep production configuration that # you likely want to automate and keep it away from # your version control system. # You can generate a new secret by running: # # mix phoenix.gen.secret config :foo, Foo.Endpoint, secret_key_base: "A LONG SECRET" # Configure your database config :foo, Foo.Repo, adapter: Ecto.Adapters.Postgres, username: "postgres", password: "postgres", database: "foo_prod", size: 20 # The amount of database connections in the pool ``` There are different ways to get this data into production. One option is to replace the data above by environment variables and set those environment variables in your production machine. This is the step that we follow [in the Heroku guides](http://www.phoenixframework.org/docs/heroku). Another approach is to configure the file above and place it in your production machines apart from your code checkout, for example, at "/var/config.prod.exs". After doing so, you will have to import it from `config/prod.exs`. Search for the `import_config` line and replace it by the proper path: ```elixir import_config "/var/config.prod.exs" ``` With your secret information properly secured, it is time to configure assets! Before taking this step, we need to do one bit of preparation. Since we will be readying everything for production, we need to do some setup in that environment by getting our dependencies and compiling. ```console $ mix deps.get --only prod $ MIX_ENV=prod mix compile ``` ## Compiling your application assets This step is required only if you have static assets like images, javascript, stylesheets and more in your Phoenix applications. By default, Phoenix uses brunch, and that's what we are going to explore. Compilation of static assets happens in two steps: ```console $ brunch build --production $ MIX_ENV=prod mix phoenix.digest Check your digested files at "priv/static". ``` And that is it! The first command builds the assets and the second generates digests as well as a manifest file so Phoenix can quickly serve assets in production. Keep in mind that, if you by any chance forget to run the steps above, Phoenix will show an error message: ```console $ PORT=4001 MIX_ENV=prod mix phoenix.server 10:50:18.732 [info] Running MyApp.Endpoint with Cowboy on http://example.com 10:50:18.735 [error] Could not find static manifest at "my_app/_build/prod/lib/foo/priv/static/manifest.json". Run "mix phoenix.digest" after building your static files or remove the configuration from "config/prod.exs". ``` The error message is quite clear: it says Phoenix could not find a static manifest. Just run the commands above to fix it or, if you are not serving or don't care about assets at all, you can just remove the `cache_static_manifest` configuration from `config/prod.exs`. ## Starting your server in production To run Phoenix in production, we need to set the `PORT` and `MIX_ENV` environment variables when invoking `mix phoenix.server`: ```console $ PORT=4001 MIX_ENV=prod mix phoenix.server 10:59:19.136 [info] Running MyApp.Endpoint with Cowboy on http://example.com ``` In case you get an error message, please read it carefully, and open up a bug report if it is still not clear how to address it. You can also run your application inside an interactive shell: ```console $ PORT=4001 MIX_ENV=prod iex -S mix phoenix.server 10:59:19.136 [info] Running MyApp.Endpoint with Cowboy on http://example.com ``` Or run it detached from the iex console. This effectively daemonizes the process so it can run independently in the background: ```elixir MIX_ENV=prod PORT=4001 elixir --detached -S mix do compile, phoenix.server ``` Running the application in detached mode allows us to keep the application running even after we terminate the shell connection with the server. ## Putting it all together The previous sections give an overview about the main steps required to deploy your Phoenix application. In practice, you will end-up adding steps of your own as well. For example, if you are using a database, you will also want to run `mix ecto.migrate` before starting the server to ensure your database is up to date. Overall, here is a script you can use as starting point: ```elixir # Initial setup $ mix deps.get --only prod $ MIX_ENV=prod mix compile # Compile assets $ brunch build --production $ MIX_ENV=prod mix phoenix.digest # Custom tasks (like DB migrations) $ MIX_ENV=prod mix ecto.migrate # Finally run the server $ PORT=4001 MIX_ENV=prod mix phoenix.server ```