Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products. If you have feedback or questions as you navigate the site, click Send Feedback.

Storing and serving static files

Stay organized with collections Save and categorize content based on your preferences.

Applications often need to serve static files such as JavaScript, images, and CSS in addition to handling dynamic requests. Apps in the standard environment can serve static files from a Google Cloud option like Cloud Storage, serve them directly, or use a third-party content delivery network (CDN).

Hosting your static site on Google Cloud can cost less than using a traditional hosting provider, as Google Cloud provides a free tier.

Serving files from Cloud Storage

Cloud Storage can host static assets for dynamic web apps. The benefits of using Cloud Storage instead of serving directly from your app include:

  • Cloud Storage essentially works as a content delivery network. This does not require any special configuration because by default any publicly readable object is cached in the global Cloud Storage network.
  • Your app's load will be reduced by offloading serving static assets to Cloud Storage. Depending on how many static assets you have and the frequency of access, this can reduce the cost of running your app by a significant amount.
  • Bandwidth charges for accessing content can often be less with Cloud Storage.

You can upload your assets to Cloud Storage by using the gsutil command line tool or the Cloud Storage API.

The Google Cloud Client Library provides an idiomatic client to Cloud Storage, for storing and retrieving data with Cloud Storage in an App Engine app.

Note that the PHP 7+ client also provides an API-backed stream wrapper which can be used to interact with Cloud Storage as a specialized file system.

Example of serving from a Cloud Storage bucket

This simple example creates a Cloud Storage bucket and uploads static assets using Google Cloud CLI:

  1. Create a bucket. It's common, but not required, to name your bucket after your project ID. The bucket name must be globally unique.

    gsutil mb gs://<your-bucket-name>
  2. Set the ACL to grant read access to items in the bucket.

    gsutil defacl set public-read gs://<your-bucket-name>
  3. Upload items to the bucket. The rsync command is typically the fastest and easiest way to upload and update assets. You could also use cp.

    gsutil -m rsync -r ./static gs://<your-bucket-name>/static

You can now access your static assets via<your-bucket-name>/static/....

For more details on how to use Cloud Storage to serve static assets, including how to serve from a custom domain name, refer to How to Host a Static Website.

Serving files from other Google Cloud services

You also have the option of using Cloud CDN or other Google Cloud storage services.

Serving files directly from your app

To serve static files in the standard environment, you define the handlers in your app.yaml file using either the static_dir or static_files elements.

The content in the static files or static directories are unaffected by the scaling settings in your app.yaml file. Requests to static files or static directories are handled by the App Engine infrastructure directly, and do not reach the language runtime of the application.

Configuring your static file handlers

To configure your app to serve the ./public directory from the /static URL, you define a handler in your app.yaml file.

The following demonstrates how to serve the static files of a sample app's ./public directory. The template for this app's index.html page instructs the browser to load the main.css file, for example:

<link type="text/css" rel="stylesheet" href="/static/css/main.css">

The ./public directory is defined in the static_dir element of the project's app.yaml file:

  - url: /favicon\.ico
    static_files: favicon.ico
    upload: favicon\.ico

  - url: /static
    static_dir: public

  - url: /.*
    secure: always
    redirect_http_response_code: 301
    script: auto

The handlers section in the above example handles three URL patterns:

  • The /favicon.ico handler maps a request specifically for /favicon.ico to a file named favicon.ico in the app's root directory.

  • The /static handler maps requests for URLs that start with /static. When App Engine receives a request for a URL beginning with /static, it maps the remainder of the path to files in the ./public directory. If an appropriate file is found in the directory, the contents of that file are returned to the client.

  • The /.* handler matches all other URLs and directs them to your app.

URL path patterns are tested in the order they appear in app.yaml, therefore the pattern for your static files should be defined before the /.* pattern. For more information, see the app.yaml reference.


No additional information for this runtime.


Example of serving static files in a Spring Boot app

For example, to serve all static files that are located in the BOOT-INF/classes/static directory of a Spring Boot app, complete the following steps before you deploy the app:

  1. Unpack the JAR file that contains all your app's classes (also known as a fat JAR).

  2. Add the following entrypoint field to your app.yaml configuration file:

    entrypoint: java -noverify BOOT-INF/resources/:BOOT-INF/classes/:BOOT-INF/lib/* com.mycompany.myapp.YOUAPPCLASSNAME
  3. Add the following handlers to your app.yaml file to configure static resources (this is always needed when using an unpacked fat JAR):

      - url: (/.*)
        static_files: BOOT-INF/classes/static\1
        upload: BOOT-INF/classes/static/.*\.(gif|png|jpg|svg|ico|css|js|html)$
        require_matching_file: True
        login: optional
        secure: optional

Then deploy the app.


Serving files for local development

Most web frameworks include support for serving static files, which you can use to serve files locally during development.

In the following example, the app uses the express.static middleware to serve files from the ./public directory to the /static URL. Specifically, the example app is serving a stylesheet that is located in ./public/css, from the URL /static/main.css.

'use strict';

const express = require('express');
const app = express();

app.set('view engine', 'pug');

// Use the built-in express middleware for serving static files from './public'
app.use('/static', express.static('public'));

app.get('/', (req, res) => {

// Start the server
const PORT = parseInt(process.env.PORT) || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');

The view refers to /static/main.css.

doctype html
    title Static Files
    link(rel="stylesheet", href="/static/main.css")
    p This is a static file serving example.

Other Node.js frameworks, such as Hapi, Koa, and Sails typically support serving static files directly from the app. Refer to their documentation for details on how to configure and use static content.


Serving files for local development

Use PHP's built-in webserver to serve static files locally:

  1. Navigate to your project directory.
  2. Start your local webserver with the following command:

    php -S localhost:8080
  3. Target your locally running PHP application with a request for static files using the curl HTTP request utility:

    curl -O http://localhost:8080/static/file/path/image.png

    The request above retrieves the ./static/file/path/image.png file.

Many web frameworks include support for serving static files, which you can use to serve files locally during development instead of a local webserver. For example, see the framework documentation for Symfony's Serving Files or Laravel's File Responses.


Note that to use static handlers, you must either specify the entrypoint element in app.yaml or specify a handler with script set to auto.


No additional information for this runtime.

Serving from a third-party content delivery network

You can use any external third-party CDN to serve your static files and cache dynamic requests but your app might experience increased latency and cost.

For improved performance, you should use a third-party CDN that supports CDN Interconnect.