"Hello, World!" for Custom Runtimes

Custom runtimes 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 the environment is customized, you can still manage it with the App Engine flexible environment toolchain for deployment and provisioning, and receive all the benefits of the App Engine flexible environment.

Applications using custom runtimes can take advantage of Cloud Platform services using the public REST APIs or client libraries, such as the Google Client Libraries.

We will launch an nginx webserver using a custom runtime software stack.

Before you begin

Before running this sample, complete the steps below.

1. Create a project in the Google Cloud Platform Console

You can manage all the Google Cloud Platform resources for your application, including deployment, access control, billing, and services, from the Cloud Platform Console.

  1. Go to the Cloud Platform Console.
  2. Click Create Project.
  3. Name your project and note the project ID, which will be used for commands and configuration.
  4. Enable billing for your project.

2. Install the Google Cloud SDK

Follow the instructions for installation on your operating system by clicking on this button. Return here when you are done.

Download the Google Cloud SDK

3. Authenticate, update, and initialize your environment

Open a terminal and use the gcloud init command to perform authentication and set up the default configuration.

gcloud init

Download the app

Clone the Hello World sample app repository to your local machine:

git clone https://github.com/GoogleCloudPlatform/appengine-custom-runtimes-samples

Then go to the directory that contains the sample code:

cd appengine-custom-runtimes-samples/nginx

Code review

app.yaml specifies the deployment configuration:

runtime: custom
env: flex

runtime: custom 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.

The Dockerfile is the set of instructions needed to create a Docker image. This Dockerfile installs the nginx webserver 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.

Running Hello World on your local machine

You can test your app by downloading Docker and running your container to test its behaviour.

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

Running Hello World on App Engine

You are now ready to deploy your app to the cloud.

Open a terminal window and go to the directory where your app.yaml is located. Remember that the Dockerfile and app.yaml must be in the same location as gcloud only looks for the Dockerfile in the same directory where app.yaml is located. Now enter the following command to deploy your app:

gcloud app deploy

To see your app run in the cloud, enter the following address in your web browser:


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