Phoenix Static File Serving

When to Use

Use when serving uploaded files, assets, or any static content through Phoenix.

Critical Concept

If you reference a path like /uploads/photo.jpg in your app, the directory "uploads" MUST be in static_paths() or the file won't be served!

Configuration Required

1. Define static_paths/0

# lib/my_app_web.ex
def static_paths do
  ~w(assets fonts images uploads favicon.ico robots.txt)
end

Rule: Any directory you serve files from must be listed here.

2. Verify Plug.Static Configuration

# lib/my_app_web/endpoint.ex
plug Plug.Static,
  at: "/",
  from: :my_app,
  gzip: false,
  only: MyAppWeb.static_paths()

The only: MyAppWeb.static_paths() line ensures only configured directories are served.

Common Patterns

User Uploads

# Save uploaded file
dest = Path.join(["priv", "static", "uploads", filename])
File.mkdir_p!(Path.dirname(dest))
File.cp!(source, dest)

# Store path in database
path = "/uploads/#{filename}"

# MUST add to static_paths
def static_paths, do: ~w(assets uploads favicon.ico)

Generated Content

# For dynamically generated images, charts, PDFs
def static_paths, do: ~w(assets uploads generated exports favicon.ico)

Multiple Upload Directories

# Different directories for different content types
def static_paths do
  ~w(
    assets
    uploads/images
    uploads/documents
    uploads/avatars
    generated
    favicon.ico
  )
end

File Structure

Static files must be in priv/static/:

my_app/
├── priv/
│   └── static/
│       ├── assets/        # CSS, JS (from esbuild)
│       ├── uploads/       # User uploads
│       │   ├── image1.jpg
│       │   └── doc.pdf
│       ├── generated/     # Generated files
│       └── favicon.ico

Serving Files

From Templates

<!-- Image -->
<img src="/uploads/photo.jpg" alt="Photo" />

<!-- Document download -->
<.link href="/uploads/document.pdf" download>Download</.link>

<!-- Static asset -->
<img src={~p"/images/logo.png"} alt="Logo" />

From Controllers

def download(conn, %{"filename" => filename}) do
  path = Path.join(["priv", "static", "uploads", filename])

  if File.exists?(path) do
    send_download(conn, {:file, path}, filename: filename)
  else
    conn
    |> put_status(:not_found)
    |> text("File not found")
  end
end

Troubleshooting

Files Return 404

Problem: Accessing /uploads/file.jpg returns 404

Fixes:

Check static_paths includes "uploads"
Verify file exists in priv/static/uploads/
Restart server after changing static_paths
Check file permissions (should be readable)

# Debug helper
def check_static_file(path) do
  full_path = Path.join(["priv", "static", path])

  cond do
    not File.exists?(full_path) ->
      "File does not exist: #{full_path}"

    not File.readable?(full_path) ->
      "File exists but not readable: #{full_path}"

    true ->
      "File OK: #{full_path}"
  end
end

Files Work in Dev but Not Production

Problem: Files serve correctly locally but fail in production

Fixes:

Run mix phx.digest before deployment:

MIX_ENV=prod mix phx.digest

Check production endpoint config:

# config/runtime.exs
config :my_app, MyAppWeb.Endpoint,
  cache_static_manifest: "priv/static/cache_manifest.json"

Ensure files are deployed:

# Check your deployment includes priv/static/

Large Files Slow Down Server

Problem: Serving large files (videos, archives) through Phoenix

Solution: Use a CDN or reverse proxy (nginx, CloudFront)

# For large files, consider streaming
def download_large(conn, %{"id" => id}) do
  file = get_file!(id)

  conn
  |> put_resp_header("content-type", file.content_type)
  |> put_resp_header("content-disposition", ~s(attachment; filename="#{file.name}"))
  |> send_chunked(200)
  |> stream_file(file.path)
end

defp stream_file(conn, path) do
  File.stream!(path, [], 2048)
  |> Enum.reduce_while(conn, fn chunk, conn ->
    case chunk(conn, chunk) do
      {:ok, conn} -> {:cont, conn}
      {:error, :closed} -> {:halt, conn}
    end
  end)
end

Security Best Practices

1. Sanitize File Paths

Never use user input directly in file paths:

# ❌ DANGEROUS - Path traversal attack
def serve_file(conn, %{"path" => user_path}) do
  send_file(conn, 200, "priv/static/#{user_path}")
end

# ✅ SAFE - Validate and constrain
def serve_file(conn, %{"filename" => filename}) do
  safe_name = Path.basename(filename)  # Remove directory traversal
  path = Path.join(["priv", "static", "uploads", safe_name])

  if File.exists?(path) and String.starts_with?(path, "priv/static/uploads") do
    send_file(conn, 200, path)
  else
    send_resp(conn, 404, "Not found")
  end
end

2. Content-Type Headers

Set proper content types to prevent XSS:

def serve_image(conn, %{"id" => id}) do
  image = get_image!(id)

  conn
  |> put_resp_header("content-type", image.content_type)
  |> put_resp_header("x-content-type-options", "nosniff")
  |> send_file(200, image.path)
end

3. Access Control

Protect sensitive files:

def download_private(conn, %{"id" => id}) do
  user = conn.assigns.current_user
  file = get_file!(id)

  if authorized?(user, file) do
    send_file(conn, 200, file.path)
  else
    send_resp(conn, 403, "Forbidden")
  end
end

CDN Integration

For production, serve static files via CDN:

# config/runtime.exs
config :my_app, MyAppWeb.Endpoint,
  static_url: [host: "cdn.example.com", port: 443, scheme: "https"]

# Now ~p"/uploads/file.jpg" generates:
# https://cdn.example.com/uploads/file.jpg

Cache Control

Set appropriate cache headers:

# In endpoint.ex
plug Plug.Static,
  at: "/",
  from: :my_app,
  only: MyAppWeb.static_paths(),
  cache_control_for_etags: "public, max-age=86400",
  headers: %{"cache-control" => "public, max-age=31536000"}

Development vs Production

# Development - serve files directly
# config/dev.exs
config :my_app, MyAppWeb.Endpoint,
  debug_errors: true,
  code_reloader: true,
  check_origin: false,
  watchers: [...]

# Production - optimize serving
# config/prod.exs
config :my_app, MyAppWeb.Endpoint,
  cache_static_manifest: "priv/static/cache_manifest.json",
  server: true

Quick Reference

# 1. Add directory to static_paths
def static_paths, do: ~w(assets uploads favicon.ico)

# 2. Create directory structure
priv/static/uploads/

# 3. Save files there
Path.join(["priv", "static", "uploads", filename])

# 4. Reference in templates
<img src="/uploads/#{filename}" />

# 5. Restart server to apply changes
mix phx.server

Common Mistakes

❌ Forgetting to add directory to static_paths ❌ Not creating the physical directory ❌ Using relative paths in templates ❌ Not restarting server after config change ❌ Trusting user-provided paths ❌ Serving files from outside priv/static/

✅ Always add directories to static_paths ✅ Create directories with File.mkdir_p! ✅ Use absolute paths like "/uploads/file" ✅ Restart after static_paths changes ✅ Validate and sanitize file paths ✅ Keep all static files in priv/static/

phoenix-static-files