Instead of configuring the Phoenix application to terminate SSL connections, we use a proxy, Traefik, to handle all SSL connections. This enables us to use Let's Encrypt for TLS certificates. Using Traefik to manage this allows automatic renewal of certificates.

Health Check

To prepare the application for production deployment, we need to add a health check. The health check in your Docker Compose file ensures that the Phoenix application inside the main container is running and ready to receive traffic before other services (like Traefik) start routing requests to it.

The health check helps to:

• Prevent routing to broken apps: If the health check fails, Traefik (and other dependent services) will not route traffic to the container.
• Support zero-downtime deployments: It ensures the app is fully up before switching traffic, which is essential for rolling updates.
• Improve observability: You can monitor container health in Docker dashboards or orchestration tools like Docker Swarm or Kubernetes.

defmodule MyappWeb.Healthcheck do
  @moduledoc """
  A plug for health check, bypasses TLS rewrites.
  """

  @behaviour Plug

  import Plug.Conn

  def init(opts), do: opts

  def call(%{request_path: "/health"} = conn, _) do
    conn
    |> send_resp(200, "")
    |> halt()
  end

  def call(conn, _), do: conn
end

Add the plug to the MyappWeb.Endpoint just after the socket definition:

  plug MyappWeb.Healthcheck

Mix Release

This article assumes you have configured your application as discussed in the previous blog post: Improving Your Elixir Configuration.

Elixir applications are prepared for deployment by running the MIX_ENV=prod mix release command. This command assembles a self-contained release that can be packaged and deployed, provided the target runs the same operating system distribution and version as the machine that ran the mix release command. The release directory includes the Erlang VM, Elixir, all code, and dependencies, which can then be deployed to the production machine.

Phoenix applications come with a Dockerfile to build Docker images. You can generate the Dockerfile by running:

mix phx.gen.release --docker

Environmental variables

To configure the deployed application we will use an .env file that will be in the same folder as the compose.yml.

Docker Compose File

This Compose file defines two primary services:

• traefik: Acts as the HTTPS reverse proxy and certificate manager.
• main: A Phoenix application container that listens on port defined in .env.

It also defines:

• A shared volume for storing SSL certificate data.
• A private network (myapp_network) connecting the services.

Traefik Service (Reverse Proxy)

services:
  traefik:
    image: traefik:v2.9

Traefik is configured as a standalone container that proxies HTTP(S) traffic to the Phoenix app.

Key configuration:

• Networks: Connects to myapp_network to route traffic to the Phoenix app.
• Volumes:
  • /var/run/docker.sock: Allows Traefik to discover running containers and their labels.
  • production_traefik:/etc/traefik/acme: Stores Let’s Encrypt TLS certificates.
• Ports:
  • 80 for HTTP.
  • 443 for HTTPS.
• Command Flags:
  • Sets up HTTP → HTTPS redirection.
  • Enables automatic TLS via Let’s Encrypt.
  • Uses Docker as a provider for service discovery.

Let's Encrypt

--certificatesResolvers.letsencrypt.acme.email=support@myapp.com
--certificatesResolvers.letsencrypt.acme.storage=/etc/traefik/acme/acme.json

Traefik automatically generates and renews TLS certificates using the provided email and stores them in the mounted volume.

Phoenix App Service (main)

Build the Phoenix application using the Dockerfile in the current directory:

  main:
    container_name: main_phoenix_app
    build:
      context: .
      dockerfile: Dockerfile

Traefik Labels

These labels instruct Traefik how to route traffic to the Phoenix app:

• Routing Rule: Matches both the root domain and www. version using the ${ENDPOINT_URL_HOST} environment variable.
• Middlewares: Handle CSRF headers, redirect http://www.* to https://, and inject forwarded HTTPS headers.
• TLS Settings: Enable HTTPS and link to the Let’s Encrypt resolver.

Compose File

volumes:
  production_traefik: {}

services:
  traefik:
    image: traefik:v2.9
    container_name: traefik
    networks:
      - myapp_network
    depends_on:
      - main
    volumes:
      - production_traefik:/etc/traefik/acme
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - '0.0.0.0:80:80'
      - '0.0.0.0:443:443'
    restart: unless-stopped
    labels:
      - "application=traefik"
    command:
      - --log.level=INFO
      - --entryPoints.web.address=:80
      - --entryPoints.web.http.redirections.entryPoint.to=web-secure
      - --entryPoints.web.http.redirections.entryPoint.scheme=https
      - --entryPoints.web-secure.address=:443
      - --certificatesResolvers.letsencrypt.acme.email=support@myapp.com
      - --certificatesResolvers.letsencrypt.acme.storage=/etc/traefik/acme/acme.json
      - --certificatesResolvers.letsencrypt.acme.httpChallenge.entryPoint=web
      - --providers.docker=true
      - --providers.docker.exposedByDefault=false

  main:
    container_name: main_phoenix_app
    build:
      context: .
      dockerfile: Dockerfile
    env_file:
      - .env
    expose:
      - ${PORT}
    labels:
      - "application=main_phoenix_app"
      - "traefik.enable=true"
      - "traefik.http.middlewares.csrf.headers.hostsproxyheaders=X-CSRFToken"
      - "traefik.http.middlewares.redirect-https-www.redirectregex.regex=^https?://www\\.(.+)"
      - "traefik.http.middlewares.redirect-https-www.redirectregex.replacement=https://$${1}"
      - "traefik.http.middlewares.redirect-https-www.redirectregex.permanent=true"
      - "traefik.http.middlewares.forwarded-headers.headers.customrequestheaders.X-Forwarded-Proto=https"
      - "traefik.http.routers.main.rule=(Host(`${ENDPOINT_URL_HOST}`) || Host(`www.${ENDPOINT_URL_HOST}`)) && PathPrefix(`/`)"
      - "traefik.http.routers.main.priority=1"
      - "traefik.http.routers.main.entryPoints=web-secure"
      - "traefik.http.routers.main.middlewares=redirect-https-www,csrf,forwarded-headers"
      - "traefik.http.routers.main.tls.certResolver=letsencrypt"
      - "traefik.http.routers.main.tls=true"
      - "traefik.http.services.main.loadBalancer.server.port=${PORT}"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${PORT}/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - myapp_network
    restart: unless-stopped

networks:
  myapp_network:

Conclusion

In this article, we demonstrated how to deploy a Phoenix application to production using Docker Compose and Traefik as a reverse proxy. By offloading SSL termination to Traefik and automating certificate management with Let’s Encrypt, you simplify your deployment and ensure secure HTTPS connections. Adding a health check improves reliability and supports zero-downtime deployments. This setup provides a robust foundation for deploying Phoenix apps in production environments.

To see the code changes, check out this PR

2025-05-20

• Fix bugs in config
• Add example .env file
• Add GitHub link to PR

Main article

Configuration in the Elixir ecosystem has undergone multiple changes over the years. Configuration scripts are used to configure elixir applications during the compile phase depending on the environment in which it is running ie:

• config/test.exs for test environments
• config/dev.exs for development environments
• config/prod.exs for prodution environments.

Overtime this resulted in problems since a new file needed to be added for every new environment, eg: staging environment, requiring compilation of the code again. This would not work in CI/CD environments since the same binary that was tested is expected to be used in production.

In Elixir 1.11 support for using config/runtime.exs which allowed for runtime configuration in all environments. The current structure of the config folder is as follows:

config
├── config.exs
├── dev.exs
├── prod.exs
├── runtime.exs
└── test.exs

Current config file structures

If we look deeper into each of the configuration files with all the comments removed we can see that there is a lot of duplication.

Config file

import Config

config :myapp, :scopes,
  user: [
    default: true,
    module: Myapp.Accounts.Scope,
    assign_key: :current_scope,
    access_path: [:user, :id],
    schema_key: :user_id,
    schema_type: :id,
    schema_table: :users,
    test_data_fixture: Myapp.AccountsFixtures,
    test_login_helper: :register_and_log_in_user
  ]

config :myapp,
  ecto_repos: [Myapp.Repo],
  generators: [timestamp_type: :utc_datetime]

config :myapp, MyappWeb.Endpoint,
  url: [host: "localhost"],
  adapter: Bandit.PhoenixAdapter,
  render_errors: [
    formats: [html: MyappWeb.ErrorHTML, json: MyappWeb.ErrorJSON],
    layout: false
  ],
  pubsub_server: Myapp.PubSub,
  live_view: [signing_salt: "GkZs+o4a"]

config :myapp, Myapp.Mailer, adapter: Swoosh.Adapters.Local

config :esbuild,
  version: "0.17.11",
  myapp: [
    args:
      ~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/*),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ]

config :tailwind,
  version: "4.0.9",
  myapp: [
    args: ~w(
      --input=assets/css/app.css
      --output=priv/static/assets/css/app.css
    ),
    cd: Path.expand("..", __DIR__)
  ]

config :logger, :default_formatter,
  format: "$time $metadata[$level] $message\n",
  metadata: [:request_id]

config :phoenix, :json_library, Jason

import_config "#{config_env()}.exs"

The last line import_config "#{config_env()}.exs" reads the config file associated with the current environment.

Test config file

import Config

config :bcrypt_elixir, :log_rounds, 1

config :myapp, Myapp.Repo,
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  database: "myapp_test#{System.get_env("MIX_TEST_PARTITION")}",
  pool: Ecto.Adapters.SQL.Sandbox,
  pool_size: System.schedulers_online() * 2

config :myapp, MyappWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 4002],
  secret_key_base: "6tvc42QacLkrYkrabIP+Xhj0LFaiF7bCNp4kMY5VT41zVVvFHywZB0Tq/F5PmjSJ",
  server: false

config :myapp, Myapp.Mailer, adapter: Swoosh.Adapters.Test

config :swoosh, :api_client, false

config :logger, level: :warning

config :phoenix, :plug_init_mode, :runtime

config :phoenix_live_view, enable_expensive_runtime_checks: true

Dev config file

import Config

config :myapp, Myapp.Repo,
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  database: "myapp_dev",
  stacktrace: true,
  show_sensitive_data_on_connection_error: true,
  pool_size: 10

config :myapp, MyappWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 4000],
  check_origin: false,
  code_reloader: true,
  debug_errors: true,
  secret_key_base: "2UQSRkWSJcN3LSaNF6ZclG2Zv8ZpuEuGXDIiFSkE8z8a1AczuxJDDTGc3trNoQQu",
  watchers: [
    esbuild: {Esbuild, :install_and_run, [:myapp, ~w(--sourcemap=inline --watch)]},
    tailwind: {Tailwind, :install_and_run, [:myapp, ~w(--watch)]}
  ]

config :myapp, MyappWeb.Endpoint,
  live_reload: [
    web_console_logger: true,
    patterns: [
      ~r"priv/static/(?!uploads/).*(js|css|png|jpeg|jpg|gif|svg)$",
      ~r"priv/gettext/.*(po)$",
      ~r"lib/myapp_web/(controllers|live|components)/.*(ex|heex)$"
    ]
  ]

config :myapp, dev_routes: true

config :logger, :default_formatter, format: "[$level] $message\n"

config :phoenix, :stacktrace_depth, 20

config :phoenix, :plug_init_mode, :runtime

config :phoenix_live_view,
  debug_heex_annotations: true,
  enable_expensive_runtime_checks: true

config :swoosh, :api_client, false

Prod config file

import Config

config :myapp, MyappWeb.Endpoint, cache_static_manifest: "priv/static/cache_manifest.json"

config :swoosh, api_client: Swoosh.ApiClient.Req

config :swoosh, local: false

config :logger, level: :info

Runtime config file

import Config

if System.get_env("PHX_SERVER") do
  config :myapp, MyappWeb.Endpoint, server: true
end

if config_env() == :prod do
  database_url =
    System.get_env("DATABASE_URL") ||
      raise """
      environment variable DATABASE_URL is missing.
      For example: ecto://USER:PASS@HOST/DATABASE
      """

  maybe_ipv6 = if System.get_env("ECTO_IPV6") in ~w(true 1), do: [:inet6], else: []

  config :myapp, Myapp.Repo,
    # ssl: true,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
    socket_options: maybe_ipv6

  secret_key_base =
    System.get_env("SECRET_KEY_BASE") ||
      raise """
      environment variable SECRET_KEY_BASE is missing.
      You can generate one by calling: mix phx.gen.secret
      """

  host = System.get_env("PHX_HOST") || "example.com"
  port = String.to_integer(System.get_env("PORT") || "4000")

  config :myapp, :dns_cluster_query, System.get_env("DNS_CLUSTER_QUERY")

  config :myapp, MyappWeb.Endpoint,
    url: [host: host, port: 443, scheme: "https"],
    http: [
      ip: {0, 0, 0, 0, 0, 0, 0, 0},
      port: port
    ],
    secret_key_base: secret_key_base
end

If we look at the above code we can see alot of duplication of application configuration. Adding new configuration needs updates to 3 files. Also, the config/runtime.exs reads environment variables in production mode. There is no reason that we cannot use environmental variables to configure all the environments instead of production only.

Configuration improvements

In order to improve the configuration we can combine the configuration into 2 files config/config.exs and config/runtime.exs only. To do this we have to follow the following rules:

1. Config that does not change depending on an environment should all be in the config/config.exs file
2. Config that varies by environment but is hardcoded should also be in the config/config.exs file inside if function blocks eg:

   if config_env() == :test do
    config :swoosh, :api_client, false
   end
   

3. All other configuration should be stored in the config/runtime.exs file and should parse operating system environment variables.

The new config folder should look as:

config
├── config.exs
└── runtime.exs

New config.exs file

import Config

config :myapp, :scopes,
  user: [
    default: true,
    module: Myapp.Accounts.Scope,
    assign_key: :current_scope,
    access_path: [:user, :id],
    schema_key: :user_id,
    schema_type: :id,
    schema_table: :users,
    test_data_fixture: Myapp.AccountsFixtures,
    test_login_helper: :register_and_log_in_user
  ]

config :myapp,
  ecto_repos: [Myapp.Repo],
  generators: [timestamp_type: :utc_datetime]

config :myapp, MyappWeb.Endpoint,
  adapter: Bandit.PhoenixAdapter,
  render_errors: [
    formats: [html: MyappWeb.ErrorHTML, json: MyappWeb.ErrorJSON],
    layout: false
  ],
  pubsub_server: Myapp.PubSub,
  live_view: [signing_salt: "GkZs+o4a"],
  code_reloader: config_env() == :dev,
  debug_errors: config_env() == :dev,
  check_origin: config_env() == :prod

config :esbuild,
  version: "0.17.11",
  myapp: [
    args:
      ~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/*),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ]

config :tailwind,
  version: "4.0.9",
  myapp: [
    args: ~w(
      --input=assets/css/app.css
      --output=priv/static/assets/css/app.css
    ),
    cd: Path.expand("..", __DIR__)
  ]

config :logger, :default_formatter,
  format: "$time $metadata[$level] $message\n",
  metadata: [:request_id]

config :phoenix, :json_library, Jason

if config_env() == :test do
    config :bcrypt_elixir, :log_rounds, 1

    config :myapp, Myapp.Repo,
        pool: Ecto.Adapters.SQL.Sandbox,
        pool_size: System.schedulers_online() * 2

    config :logger, level: :warning

    config :phoenix, :plug_init_mode, :runtime

    config :phoenix_live_view, enable_expensive_runtime_checks: true
end

if config_env() == :dev do
config :myapp, MyappWeb.Endpoint,
  watchers: [
    esbuild: {Esbuild, :install_and_run, [:myapp, ~w(--sourcemap=inline --watch)]},
    tailwind: {Tailwind, :install_and_run, [:myapp, ~w(--watch)]}
  ],
  live_reload: [
    web_console_logger: true,
    patterns: [
      ~r"priv/static/(?!uploads/).*(js|css|png|jpeg|jpg|gif|svg)$",
      ~r"priv/gettext/.*(po)$",
      ~r"lib/myapp_web/(controllers|live|components)/.*(ex|heex)$"
    ]
  ]

config :myapp, dev_routes: true

config :logger, :default_formatter, format: "[$level] $message\n"

config :phoenix, :stacktrace_depth, 20

config :phoenix, :plug_init_mode, :runtime

config :phoenix_live_view,
  debug_heex_annotations: true,
  enable_expensive_runtime_checks: true

end

if config_env() == :prod do
    config :logger, level: :info
end

New runtime.exs config file

import Config

database_username =
  System.get_env("DATABASE_USERNAME") ||
    raise """
    environment variable DATABASE_USERNAME is missing.
    For example: postgress
    """

database_password =
  System.get_env("DATABASE_PASSWORD") ||
    raise """
    environment variable DATABASE_PASSWORD is missing.
    For example: postgress
    """

database_hostname =
  System.get_env("DATABASE_HOSTNAME") ||
    raise """
    environment variable DATABASE_HOSTNAME is missing.
    For example: localhost
    """

database_database =
  System.get_env("DATABASE_DATABASE") ||
    raise """
    environment variable DATABASE_DATABASE is missing.
    For example: myapp
    """

secret_key_base =
  System.get_env("SECRET_KEY_BASE") ||
    raise """
    environment variable SECRET_KEY_BASE is missing.
    You can generate one by calling: mix phx.gen.secret
    """

endpoint_url_host =
  System.get_env("ENDPOINT_URL_HOST") ||
    raise """
    environment variable ENDPOINT_URL_HOST is missing.
    For example: "example.com"
    """

endpoint_url_port =
  System.get_env("ENDPOINT_URL_PORT") ||
    raise """
    environment variable ENDPOINT_URL_PORT is missing.
    For example: "80"
    """

endpoint_http_port =
  System.get_env("PORT") ||
    raise """
    environment variable PORT is missing.
    For example: "4000"
    """

config :myapp, Myapp.Repo,
  username: database_username,
  password: database_password,
  hostname: database_hostname,
  database: database_database,
  stacktrace: config_env() == :dev,
  show_sensitive_data_on_connection_error: config_env() == :dev,
  pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
  socket_options: if(System.get_env("ECTO_IPV6") in ~w(true 1), do: [:inet6], else: []),

if config_env() == :test do
  config :myapp, Myapp.Repo,
    database: "#{database_database}#{System.get_env("MIX_TEST_PARTITION")}",
    pool: Ecto.Adapters.SQL.Sandbox,
    pool_size: System.schedulers_online() * 2
end

config :myapp, MyappWeb.Endpoint,
  url: [
    host: endpoint_url_host,
    port: String.to_integer(endpoint_url_port),
    scheme: if(config_env() == :prod, do: "https", else: "http")
  ],
  http: [
    port: String.to_integer(endpoint_http_port),
    ip: if(config_env() == :prod, do: {0, 0, 0, 0, 0, 0, 0, 0}, else: {127, 0, 0, 1})
  ],
  secret_key_base: secret_key_base,
  server: String.to_existing_atom(System.get_env("PHX_SERVER", "false"))

swooch_adapter =
  case config_env() do
    :dev -> Swoosh.Adapters.Local
    # In test we don't send emails.
    :test -> Swoosh.Adapters.Test
    :prod -> Swoosh.Adapters.MailGun
  end

config :myapp, Myapp.Mailer,
  adapter: Swoosh.Adapters.Test,
  api_client: false,
  local: true

if config_env() == :dev do
  config :myapp, Myapp.Mailer, adapter: Swoosh.Adapters.Local
end

if config_env() == :prod do
  config :myapp, Myapp.Mailer,
    api_key: System.get_env("MAILGUN_API_KEY"),
    domain: System.get_env("MAILGUN_DOMAIN"),
    local: false,
    api_client: Swoosh.ApiClient.Req

  config :myapp, :dns_cluster_query, System.get_env("DNS_CLUSTER_QUERY")
end

Setting environmental variables

The configuration has been changed to use environmental variables, this is not a problem in production where it is usually recommended to use in the 12 factor. However in development and testing this can be a problem since it is not easy to set the environmental variables in the operation system. To simply this we will update the config to make use .env files.

To do this we will need to add an external dependency Dotenvy:

def deps do
  [
    {:dotenvy, "~> 1.0.0"}
  ]
end

Then run mix deps.get

The config/runtime.exs file is updated to include the following block at the beginning:

# config/runtime.exs
import Config
import Dotenvy

env_dir_prefix = System.get_env("RELEASE_ROOT") || Path.expand("./envs")

source!([
  Path.absname(".env", env_dir_prefix),
  Path.absname(".#{config_env()}.env", env_dir_prefix),
  Path.absname(".#{config_env()}.overrides.env", env_dir_prefix),
  System.get_env()
])

The above example would include the envs/.env file for shared/default configuration values and then leverage environment-specific .env files (e.g. envs/.dev.env) to provide environment-specific values. An envs/.{MIX_ENV}.overrides.env file would be referenced in the .gitignore file to allow developers to override any values a file that is not under version control. System environment variables are given final say over the values via System.get_env().

Dotenvy.env!/2 is used to read the given variable and convert its value to a given type. This function will raise an error if the given variable does not exist.

Updated config/runtime.exs file:

config :myapp, Myapp.Repo,
  username: env!("DATABASE_USERNAME"),
  password: env!("DATABASE_PASSWORD"),
  hostname: env!("DATABASE_HOSTNAME"),
  database: env!("DATABASE_DATABASE"),
  stacktrace: config_env() == :dev,
  show_sensitive_data_on_connection_error: config_env() == :dev,
  pool_size: env!("POOL_SIZE", :integer, 10),
  socket_options: if(env!("ECTO_IPV6") in ~w(true 1), do: [:inet6], else: [])

if config_env() == :test do
  config :myapp, Myapp.Repo,
    database: "#{env!("DATABASE_DATABASE")}#{env!("MIX_TEST_PARTITION", :integer, 1)}",
    pool: Ecto.Adapters.SQL.Sandbox,
    pool_size: System.schedulers_online() * 2
end

config :myapp, MyappWeb.Endpoint,
  url: [
    host: env!("ENDPOINT_URL_HOST"),
    port: env!("ENDPOINT_URL_PORT", :integer),
    scheme: if(config_env() == :prod, do: "https", else: "http")
  ],
  http: [
    port: env!("PORT", :integer),
    ip: if(config_env() == :prod, do: {0, 0, 0, 0, 0, 0, 0, 0}, else: {127, 0, 0, 1})
  ],
  secret_key_base: env!("SECRET_KEY_BASE"),
  server: env!("PHX_SERVER", :boolean, false)


config :myapp, Myapp.Mailer,
  adapter: Swoosh.Adapters.Test,
  api_client: false,
  local: true

if config_env() == :dev do
  config :myapp, Myapp.Mailer, adapter: Swoosh.Adapters.Local
end

if config_env() == :prod do
  config :myapp, Myapp.Mailer,
    adapter: Swoosh.Adapters.MailGun,
    api_key: env!("MAILGUN_API_KEY"),
    domain: env!("MAILGUN_DOMAIN"),
    local: false,
    api_client: Swoosh.ApiClient.Req

  config :myapp, :dns_cluster_query, env!("DNS_CLUSTER_QUERY")
end

Example .env file

# Database Configuration
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
DATABASE_HOSTNAME=localhost
DATABASE_DATABASE=myapp_dev
POOL_SIZE=10
ECTO_IPV6=false

# Phoenix Endpoint
PHX_SERVER=false
ENDPOINT_URL_HOST=localhost
ENDPOINT_URL_PORT=80
PORT=4000
SECRET_KEY_BASE=your_secret_key_here
PHX_SERVER=true

# Mailer (for production)
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=your-mailgun-domain.com

# Optional clustering support
DNS_CLUSTER_QUERY=myapp.local

# Testing (optional for test partitioning)
MIX_TEST_PARTITION=1

Conclusion

By consolidating configuration into just two files, using runtime variables, and leveraging .env support with Dotenvy, your Elixir app becomes:

• Easier to manage across environments
• CI/CD-friendly and immutable-build ready
• Aligned with 12-factor and containerized deployment standards

To view the code here is the PR for the code changes

Material Symbols is the variable font version of Google’s Material Icons. Unlike traditional icon fonts, variable fonts allow a single file to contain multiple stylistic variations—significantly reducing the number of assets you need to manage.

Material Symbols replaces the now-deprecated Material Icons fonts and is actively maintained with regular updates.

Why Use Material Symbols in Phoenix?

By default, new Phoenix projects include a set of built-in components, including an icon/1 component that renders Heroicons. While Heroicons are elegant and often sufficient, Material Symbols offer a far larger collection. They're widely adopted by UI designers, which means many mockups and design systems use them by default.

To preserve visual fidelity with the design, substituting icons between sets (like Heroicons and Material Symbols) is not ideal. Having Material Symbols available directly in your Phoenix app makes it easier to match designs precisely.

Material Symbols Overview

Material Symbols are based on 24px icons and come in three styles:

• Outlined
• Rounded
• Sharp

These are variable fonts with four axes of customization:

• Optical Size: Default is 24
• Weight: Default is 400 (Regular)
• Grade: Default is 0
• Fill: Default is 0

For simplicity, we'll use the default values and only include the 400 weight icons.

Installing Material Symbols via Dependency

To avoid manually downloading and maintaining icon files, we can pull them directly from GitHub using a sparse checkout in mix.exs. This setup fetches only the necessary svg/400 folder, avoids compiling the dependency, and reduces disk usage by limiting Git history.

Add the following to your mix.exs dependencies:

{:material_icons,
  github: "marella/material-symbols",
  sparse: "svg/400",
  app: false,
  compile: false,
  depth: 1
}

Then run:

mix deps.get

Extending the icon/1 Component

Phoenix comes with a built-in icon/1 component for Heroicons. We’ll add support for Material Symbols by introducing a new clause that matches icon names with a material- prefix.

In core_components.ex, add this function:

def icon(%{name: "material-" <> _} = assigns) do
  ~H"""
  <span class={[@name, @class]} aria-hidden="true" {@rest} />
  """
end

This allows you to use Material Symbols like so:

<.icon name="material-home" />

Configuring Tailwind to Recognize Material Symbols

Next, we need Tailwind to generate CSS classes for the Material Symbols. We’ll scan the SVG files in the deps/material_icons directory and create utility classes based on their filenames.

Update your tailwind.config.js with the following plugin:

plugin(function({ matchComponents, theme }) {
  const path = require("path");
  const fs = require("fs");

  const iconsDir = path.join(__dirname, "../deps/material_icons/svg/400");
  const values = {};

  const styles = [
    ["", "outlined"],
    ["_rounded", "rounded"],
    ["_sharp", "sharp"],
  ];

  styles.forEach(([suffix, dir]) => {
    fs.readdirSync(path.join(iconsDir, dir)).forEach(file => {
      let name = path.basename(file, ".svg") + suffix;
      name = name.replaceAll("_", "-");

      values[name] = {
        name,
        fullPath: path.join(iconsDir, dir, file),
      };
    });
  });

  matchComponents({
    "material": ({ name, fullPath }) => {
      let content = fs.readFileSync(fullPath, "utf8").replace(/\r?\n|\r/g, "");
      content = content.replace(' width="48" height="48"', "");

      const size = theme("spacing.6");

      return {
        [`--material-${name}`]: `url('data:image/svg+xml;utf8,${content}')`,
        "-webkit-mask": `var(--material-${name})`,
        "mask": `var(--material-${name})`,
        "mask-repeat": "no-repeat",
        "background-color": "currentColor",
        "vertical-align": "middle",
        "display": "inline-block",
        "width": size,
        "height": size,
      };
    }
  }, { values });
})

With this setup, Tailwind will generate classes like material-home based on your icons. You can then use them as utility classes in your components.

Keeping Icons Up to Date

Since the Material Symbols repository is frequently updated via GitHub Actions, your app can stay current with new icons by simply running:

mix deps.update material_icons

Conclusion

Integrating Material Symbols with Phoenix and Tailwind gives you access to a vast and regularly updated icon set that aligns with modern UI design standards. By automating the dependency, icon rendering, and Tailwind class generation, you streamline both development and design fidelity—ensuring your front end looks just like the mockups.