Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 39 ยท Build, Addons and Deployment

Deploying Ember Apps

Ship an Ember app: build for production, serve it from static hosting with history fallback, set cache headers for fingerprinted files, handle environments and use CI.

An Ember app is a single-page application: after the build, it is just static files (an HTML shell, fingerprinted JavaScript and CSS, images). Any web server or CDN can host it. There is no Node process to keep alive and nothing to render on the server, which makes deployment simple. The details that matter are three: send the right HTML for every URL, cache files correctly, and point the app at the right API in each environment.

This lesson walks through the production build, the rewrite rule that single-page apps need, cache headers, configuration, a CI pipeline and the checks to run before you ship. Command lines and config files are shown read-only; the runnable stand-ins model the server rules in plain JavaScript.

Real Ember vs stand-in. Command lines and file-named blocks are real and read-only. Runnable blocks model the server logic.

Build and inspect

Terminal
npm ci
npm test
ember build --environment=production

(Projects created with recent blueprints also provide npm run build.) Use npm ci, not npm install, on build servers so the exact versions from the lock file are used. The output goes to dist/:

Text
dist/
  index.html
  assets/
    my-app-3f9a1c4e.js
    vendor-81bd02aa.js
    my-app-9c10fe27.css
  robots.txt

index.html is the only file with a fixed name; it references the hashed assets. Upload the whole folder.

One HTML file for every URL

With locationType: 'history', your URLs look like /posts/42. That path does not exist as a file on the server, so a plain static server answers 404 when a user refreshes the page or opens a shared link. The fix is a fallback rule: if no real file matches, serve index.html and let Ember's router read the URL.

Typical configuration:

nginx

Text
location / {
  try_files $uri /index.html;
}

Netlify (public/_redirects, copied into dist/)

Text
/*    /index.html   200

Apache (.htaccess)

Text
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ /index.html [L]

If you cannot configure the server, set locationType: 'hash'; URLs become /#/posts/42 and the server only ever sees /.

The fallback must not catch missing assets. A request for /assets/old-3f9a.js should return a real 404, not index.html, otherwise browsers try to run HTML as JavaScript and users see a baffling syntax error after a deploy. Check that try_files $uri runs first and only non-file paths fall back.

The model below shows the decision a correct server makes, including the asset case.

JS Stand-in: static hosting with a history fallback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Caching: long for assets, short for the HTML

Fingerprinted assets never change under the same name, so they can be cached for a year. The HTML shell changes on every deploy (it points to the new hashes), so it must be revalidated every time.

File Header Why
/assets/*-<hash>.js|css Cache-Control: public, max-age=31536000, immutable a changed file has a new name
/index.html Cache-Control: no-cache the browser must ask whether it changed, so users get new releases
images in public/ without hashes a moderate max-age (e.g. one day) their names do not change when they do
sequenceDiagram
  participant B as Browser
  participant S as Server or CDN
  B->>S: GET /index.html
  S-->>B: 200, no-cache, references app-NEW.js
  B->>S: GET /assets/app-NEW.js
  S-->>B: 200, max-age 1 year
  Note over B,S: Next visit: index.html revalidated, app-NEW.js from cache

Only the small HTML file is checked on each visit; the large bundles come from the cache.

The helper below encodes these rules, checking whether a name contains a content hash.

JS Stand-in: choosing cache headers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Configuration per environment

The API address, feature flags and similar values are set at build time in config/environment.js (Ember CLI and the build). Two common strategies:

  • Build per environment: ember build --environment=production bakes in the production API. Simple, but staging needs its own build.
  • Runtime configuration: keep a small config.json in public/ (or injected into index.html as a <meta> tag by the deploy step) and read it at boot. One build artifact can then be promoted from staging to production unchanged.

Either way, remember that values in the bundle are public. Public keys (a maps key restricted by domain) are fine; secrets are not.

If your API is on another domain, the server must send CORS headers allowing your app's origin, or the browser blocks the requests. This is a server setting, not an Ember one.

Deployment pipelines

For a one-person project, upload dist/ to Netlify, Vercel, Cloudflare Pages, GitHub Pages or an S3 bucket behind a CDN. For larger teams, ember-cli-deploy provides a plugin pipeline: build, then upload assets to S3 or a CDN, then store the new index.html as a revision in Redis so you can activate or roll back a release without re-uploading assets.

A continuous integration workflow usually does:

  1. Check out the code, install with npm ci.
  2. Lint and run ember test (fail the pipeline if tests fail).
  3. Build with --environment=production.
  4. Upload dist/ (assets first, index.html last).
  5. Purge the CDN cache for index.html if needed.

Uploading the HTML last matters: if the new index.html went live before its assets, users would load a page pointing at files that do not exist yet. Old assets should stay available for a while, because users who loaded the old index.html still request the old hashes.

Terminal
# the shape of a deploy step
npm ci
npm test
ember build --environment=production
aws s3 sync dist/assets s3://my-bucket/assets --cache-control "public,max-age=31536000,immutable"
aws s3 cp dist/index.html s3://my-bucket/index.html --cache-control "no-cache"

Here is a model of why the order matters: it simulates users arriving during a deploy under both orders.

JS Stand-in: why upload index.html last

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Pre-launch checklist

  • ember test passes, including at least the main acceptance journeys.
  • The production build opens without console errors, with rootURL correct for where it is hosted.
  • Deep links and refreshes work (/posts/42 loads directly).
  • Missing assets return 404, not the HTML shell.
  • The index.html is no-cache; hashed assets are immutable.
  • The API URL and CORS are right, and no secrets are in the bundle.
  • A Content Security Policy is configured if your site requires one. Ember's development build uses inline scripts; production builds work with a strict policy once ember-cli-content-security-policy or your host's headers are set up correctly.
  • Error monitoring (Sentry or similar) is wired up so you hear about failures before users report them.
  • Search engines: a client-rendered app gives crawlers little HTML. If SEO matters, look at FastBoot (server-side rendering) or pre-rendering for public pages.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A user refreshes the page at /posts/42 and gets a 404 from the static host. What is the fix?

    With history URLs the server must return index.html for app routes so Ember's router can handle them.
  2. 2. Which caching setup is correct for a fingerprinted bundle and the index.html?

    The hash in the bundle name makes long caching safe, while the HTML must be revalidated to discover new hashes.
  3. 3. Why is index.html uploaded after the new assets?

    The new HTML points at new hashed files. They must exist before the HTML that references them goes live.
  4. 4. Where is it safe to put a database password for your app?

    Browsers can read all code and data in the bundle. Secrets must stay on a server behind an API.

Summary

  • A production Ember app is a static folder: ember build --environment=production, upload dist/.
  • History URLs need a fallback to index.html, but missing assets must still 404.
  • Cache fingerprinted assets for a year and revalidate index.html on every visit.
  • Configure the API per environment (build time or runtime), allow CORS on the API, and keep secrets out.
  • Automate with CI: install with npm ci, test, build, upload assets first and the HTML last.

Next: Project: A Notes App