Custom runtimeslet you build apps that run in an environment defined by aDockerfile. By using aDockerfile, you can use languages and packages that are not part of theGoogle Cloud and use the same resources and tooling that are used in theApp Engine flexible environment.

In this quickstart, annginx web server is launched toApp Engine using a custom runtime.

Before you begin

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

1. Create a new Google Cloud project by using the Google Cloud console:

   1. Open the Google Cloud console:

      Go to Projects

   2. ClickCreate Project and then name your new Google Cloud project.

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

      Go to Billing

2. Download and install the Google Cloud CLI and then initialize thegcloud CLI:

   Download the SDK

3. Run the followinggcloud command to create an App Engineapplication and specify in which geographicalregion that you want your appto run:

   gcloud app create

4. Due tochanges in the defaultbehavior for how Cloud Build uses service accounts in new projects, andsecure-by-defaultorganization policy changes, you might need to grant additional roles toyour deploying service account. For more information on granting specific roles,see thetroubleshooting guide.

Download the Hello World app

1. Choose one of the following to download the Hello World sample app fromGitHub, 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 thesample as a .zip file and then extract it to a local directory.

2. Navigate to thenginx directory where the sample code is located, forexample:

   cd appengine-custom-runtimes-samples/nginx

Running Hello World on your local machine

You can test the sample app bydownloading and installingDocker, and then runningthe Hello World container on your local machine.

There are no App Engine specific steps here so you can test the sampleapp 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 thefollowing steps:

1. From the directory where yourapp.yaml andDockerfile are located, runthe following command:

   gcloud app deploy

   Learn about theoptional flags.

2. To see your app running athttps://PROJECT_ID.REGION_ID.r.appspot.com, run the followingcommand to launch your browser:

   gcloud app browse

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

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

Caution: Deleting a project has the following effects:
• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as anappspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to theManage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then clickDelete.
3. In the dialog, type the project ID, and then clickShut down to delete the project.

What's next

Learn more about Dockerfiles at theDockerfile reference.

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

Code review

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

app.yaml

Specifies the configuration of the app. Theapp.yaml file must reside inthe same directory as theDockerfile file.

runtime:customenv:flex

Theruntime: custom entry tells App Engine to look for aDockerfile that will define your runtime's image andenv: flex specifies that you are deploying to the flexible environment.

For more information, see theapp.yaml reference.

Dockerfile

Defines the set of instructions that are used to create the Docker image forthe sample app's container. TheDockerfile file must reside in the samedirectory as theapp.yaml file. ThisDockerfile 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.FROMnginx# 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.COPYnginx.conf/etc/nginx/nginx.conf# create log dir configured in nginx.confRUNmkdir-p/var/log/app_engine# Create a simple file to handle health 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.RUNmkdir-p/usr/share/nginx/www/_ah &&\echo"healthy" >/usr/share/nginx/www/_ah/health# Finally, all static assets.ADDwww//usr/share/nginx/www/RUNchmod-Ra+r/usr/share/nginx/www

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

Using thisDockerfile, your container image will contain nginx and all content in thewww/ directory is available to your application.

The Hello World sample app also includes annginx.conffile, which contains the basic nginx configuration information, as well was theindex.htmlfile, which serves as the root page for the nginx web server.