Quickstart for Custom Runtimes in the App Engine Flexible Environment

Custom runtime let you build apps that run in an environment defined by a Dockerfile. By using a Dockerfile, you can use languages and packages that are not part of the Google Cloud Platform. Although you create a custom runtime, you are still able to use all the same resources and tooling to develop and manage your apps in the custom environment, that are use in the App Engine flexible environment.

In this quickstart, an nginx web server is launched to App Engine using a custom runtime.

Before you begin

Before running the sample app in this quickstart, you need to set up your environment and create a new Cloud Platform project for App Engine:

  1. Create a new Cloud Platform project by using the Cloud Platform Console:

    1. Open the Cloud Platform Console:

      Go to the Projects page

    2. Click Create Project and then name your new Cloud Platform project.

    3. Enable billing in your new Cloud Platform project by creating a new billing account or setting an existing one:

      Go to the Billing page

  2. Download and install the Google Cloud SDK and then initialize the gcloud tool:

    Download the SDK

  3. Run the following gcloud command to create an App Engine application and specify in which geographical region that you want your app to run:

    gcloud app create
    

App Engine Locations

App Engine is regional, which means the infrastructure that runs your apps is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your app's are run. You can generally select the region nearest to your app's users but you should consider the location of the other Cloud Platform products and services that are utilized by your app. Using services across multiple locations can affect your app's latency as well as pricing.

App Engine is available in the following regions:

  • us-central
  • us-east1
  • europe-west
  • asia-northeast1

Download the Hello World app

  1. Choose one of the following to download the Hello World sample app from GitHub, to your local machine:

    • Clone the Hello World sample app from the following repository:

      git clone https://github.com/GoogleCloudPlatform/appengine-custom-runtimes-samples
      
    • Download the sample as a .zip file and then extract it to a local directory.

  2. Navigate to the nginx directory where the sample code is located, for example:

    cd appengine-custom-runtimes-samples/nginx
    

Running Hello World on your local machine

You can test the sample app by downloading and installing Docker, and then running the Hello World container on your local machine.

There are no App Engine specific steps here so you can test the sample app using the tools and approach that you prefer.

Deploying Hello World to App Engine

When you are ready to deploy the sample app to App Engine, perform the following steps:

  1. From the directory where your app.yaml and Dockerfile are located, run the following command:

    gcloud app deploy
    

    Learn about the optional flags.

  2. To see your app running at http://YOUR_PROJECT_ID.appspot.com, run the following command to launch your browser:

    gcloud app browse
    

Common gcloud command flags

  • Include the --version flag to specify an ID that uniquely identifies that version of your app, otherwise one is generated for you. Example: --version [YOUR_VERSION_ID]
  • Include the --project flag to specify an alternate Cloud Platform project ID to what you initialized as the default in the gcloud tool. Example: --project [YOUR_PROJECT_ID]

Example:

gcloud app deploy --version pre-prod-5 --project my-sample-app

To learn more about deploying your app from the command line, see Testing and Deploying Your App . For a list of all the command flags, see the gcloud app deploy reference.

Clean up

To avoid incurring charges, you can delete your Cloud Platform project to stop billing for all the resources used within that project.

  1. In the Cloud Platform Console, go to the Projects page.

    Go to the Projects page

  2. In the project list, select the project you want to delete and click Delete project. After selecting the checkbox next to the project name, click
      Delete project
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Code review

Hello World is the simplest possible App Engine app, as it creates a single container that runs only one service and one version. This section describes each of the app's files in detail.

app.yaml

Specifies the configuration of the app. The app.yaml file must reside in the same directory as the Dockerfile file.

runtime: custom
env: flex

The runtime: custom entry tells App Engine to look for a Dockerfile that will define your runtime's image and env: flex specifies that you are deploying to the flexible environment.

For more information, see the app.yaml reference.

Dockerfile

Defines the set of instructions that are used to create the Docker image for the sample app's container. The Dockerfile file must reside in the same directory as the app.yaml file. This Dockerfile installs the nginx web server and copies some basic configuration:

# The standard nginx container just runs nginx. The configuration file added
# below will be used by nginx.
FROM nginx

# Copy the nginx configuration file. This sets up the behavior of nginx, most
# importantly, it ensure nginx listens on port 8080. Google App Engine expects
# the runtime to respond to HTTP requests at port 8080.
COPY nginx.conf /etc/nginx/nginx.conf

# create log dir configured in nginx.conf
RUN mkdir -p /var/log/app_engine

# Create a simple file to handle heath checks. Health checking can be disabled
# in app.yaml, but is highly recommended. Google App Engine will send an HTTP
# request to /_ah/health and any 2xx or 404 response is considered healthy.
# Because 404 responses are considered healthy, this could actually be left
# out as nginx will return 404 if the file isn't found. However, it is better
# to be explicit.
RUN mkdir -p /usr/share/nginx/www/_ah && \
    echo "healthy" > /usr/share/nginx/www/_ah/health

# Finally, all static assets.
ADD www/ /usr/share/nginx/www/
RUN chmod -R a+r /usr/share/nginx/www

The FROM command builds a base image using the official docker image for the nginx web server.

Using this Dockerfile, your container image will contain nginx and all content in the www/ directory is available to your application.

The Hello World sample app also includes an nginx.conf file, which contains the basic nginx configuration information, as well was the index.html file, which serves as the root page for the nginx web server.

Learning more

Learn more about Dockerfiles at the Dockerfile reference.

For information on how to create your own custom runtime, see Building Custom Runtimes.

Send feedback about...

Custom runtimes for the App Engine flexible environment