Set up Fastly

Fastly is required for Magento Enterprise Cloud Edition. It works with Varnish to provide fast caching capabilities and a Content Delivery Network (CDN) for static assets.

Get your Fastly credentials

To get Fastly credentials, open a support ticket. You must provide your fully-qualified domain name.

We’ll provide you with the following information so you can enable Fastly:

  • Fastly API key
  • Fastly service ID

Get started

Fastly recommends you do your development in its own branch because fine-tuning Fastly can be a complex process, depending on your needs and eCommerce shop size.

In the procedure that follows, make sure you branch a new environment; don’t use an existing one unless you know this is what you want to do.

To get started:
  1. Log in to your local development machine, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access, such as the web server docroot.
  3. Log in to your project:

    magento-cloud login
    
  4. List your projects:

    magento-cloud project:list
    
  5. If necessary, clone a project.

    magento-cloud project:get <project ID>
    

    Typically, you should clone the project in the web server’s docroot or a Virtual Host docroot.

  6. Change to a project directory.

    For example, cd /var/www/html/magento2

  7. List environments in the project:

    magento-cloud environment:list
    

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list.

  8. Fetch origin branches:

    git fetch origin
    
  9. Check out an environment:

    magento-cloud environment:checkout <environment ID>
    

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull updated code:

    git pull origin <environment ID>
    
  11. Create a snapshot of the environment.

    magento-cloud snapshot:create -e <environment ID>
    

Install Fastly in your new environment

  1. In your local environment root directory, enter the following commands in the order shown:

    composer config repositories.fastly-magento2 git "https://github.com/fastly/fastly-magento2.git"
    composer require fastly/magento2
    
  2. Wait for dependencies to be updated.
  3. Enter the following command:

    php bin/magento setup:upgrade && php bin/magento cache:clean
    
  4. Add, commit, and push the change:

    git add -A; git commit -m "Install Fastly"; git push origin <branch name>
    

Enable Fastly using the Magento Admin

  1. Log in to your local Magento Admin as an administrator.

    If you don’t remember your login information, enter the following command:

    magento-cloud var:list
    
  2. Click Stores > Settings > Configuration > Advanced > System.
  3. In the right pane, expand Full Page Cache.

    The page is displayed as follows.

    Choose Fastly

  4. Next to the Caching Application list, clear the Use system value check box.
  5. From the Caching Application list, click Fastly CDN as the following figure shows.

    Choose Fastly

  6. Expand Fastly Configuration.
  7. If you haven’t already created a Fastly account, follow the prompts on your screen to create one.
  8. After you receive them, enter your Fastly service ID and API key.
  9. Click Test Credentials.
  10. Make sure your credentials are correct before continuing.
  • Ignore the link to create a free Fastly account; we’ll provide your Fastly credentials.
  • With Fastly version 1.2.0 and later, you no longer need to upload your VCL to Fastly. The Upload VCL to Fastly button enables you to upload VCL snippets, which is an advanced option you can consider in a staging or production system.

Configure Fastly

Configure Fastly using the following:

  • We provide your Fastly service ID and API key.
  • Set most other Fastly configuration options in the Magento Admin.
  • You can fine-tune the Fastly configuration as discussed in Custom VCLs.

To configure Fastly in the Admin:

  1. Log in to the Magento Admin as an administrator.
  2. Click Stores > Settings > Configuration > Advanced > System.
  3. In the right pane, expand Full Page Cache.
  4. Expand Fastly Configuration.

    You can then choose caching options.

  5. When you’re done, click Save Config at the top of the page.

For details about Fastly configuration, see the Fastly documentation.

Create a custom error/maintenance page

You can optionally create a custom HTML page for errors or when your site is down for maintenance. This page can give confidence to your customers; instead of seeing HTTP error codes, they’ll see a page that explains that your site is down temporarily.

To create a custom error/maintenance page:

  1. In the Admin, in the Fastly Configuration section, expand Error/Maintenance Page as the following figure shows.

    Custom Fastly error page

  2. Click Set HTML.
  3. In the provided field, enter your HTML.

    The HTML you enter can be a maximum of 65,535 bytes in length.

    Avoid using images on your site in the event Fastly is not available. To use images, refer to Data URIs on the css-tricks site.

  4. When you’re done, click Upload.
  5. In the Magento Admin, click Save Config.

Upload any Fastly VCL snippets

A Fastly VCL snippet is an advanced option that enables you to modify Fastly behavior with service-oriented or versionless objects.

To use snippets, you must upload the Fastly VCL using the Magento Admin as follows:

  1. Log in to the Magento Admin as an administrator.
  2. Click Stores > Settings > Configuration > Advanced > System as the following figure shows:

    Choose Fastly

  3. In the right pane, expand Full Page Cache.
  4. Click Upload VCL to Fastly as the following figure shows.

    Upload a Magento VCL to Fastly

    If the Upload VCL to Fastly button does not display, you should upgrade the Fastly extension to version 1.2.0 or later. For details, see Update extensions. Fastly’s Composer name is fastly/magento2.
  5. Follow the prompts on your screen to complete the task.

Advanced configuration options

For advanced configuration options, customize the Fastly configuration.

For more information, see Fastly documentation.

Merge your Fastly branch

When you’re done with development, merge your environment with its parent environment.

For Fastly to be used in production, you must merge with the master environment.

Custom VCLs

You’re free to customize your Fastly VCL however you want, provided you follow Fastly’s guidelines for Mixing and matching Fastly VCL with custom VCL.

Failure to follow these guidelines means your customizations won’t work as expected.

Next steps