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.

Building a Go App on App Engine

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

This guide helps you get started with App Engine and become familiar with developing, deploying, and managing a Go app.

After you build your app, you can read other tutorials to learn how to integrate with other Google Cloud services and add more features to your app.


There are no costs associated with running this guide. Running this sample app alone does not exceed your free quota.

Setting up your development environment

You can either use your local machine, and use tools you're already familiar with, or Cloud Shell. Cloud Shell has the Google Cloud CLI already installed, your environment already set up, and many other features.

Local Machine

Install Go and set up the gcloud CLI as described in Setting up your development environment.

Cloud Shell

Launch Cloud Shell, which has all the tools you'll need pre-installed:

Open Cloud Shell

Creating a Google Cloud project

A project is required to use Google Cloud, and forms the basis for using all Google Cloud services.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.

  4. Enable the Cloud Build API.

    Enable the API

  5. Install the Google Cloud CLI.
  6. To initialize the gcloud CLI, run the following command:

    gcloud init
  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.

  9. Enable the Cloud Build API.

    Enable the API

  10. Install the Google Cloud CLI.
  11. To initialize the gcloud CLI, run the following command:

    gcloud init
  12. Create your App Engine app and its associated resources. You must choose a location, which cannot be changed later.
    gcloud app create

Writing a basic web service for App Engine

Learn how to write a web service and declare runtime settings.

Structuring your files

Your service will have the following file structure:

  • go-app/: directory for your Go 1.11 service.
    • app.yaml: Your service's configuration settings.
    • main.go: Your application code.

Creating the app.yaml file

Every App Engine project has an app.yaml configuration file which specifies your service's runtime environment settings. Your service will not deploy without this file.

  1. Create a new folder called go-app for your Go 1.11 service:

    mkdir go-app

  2. In your go-app/ folder, create a file called app.yaml, and add the following contents:

    # Copyright 2019 Google LLC
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    runtime: go115

    This is the simplest configuration for an App Engine app. It indicates to App Engine that you're using the Go 1.11 runtime. The app.yaml file can also specify network settings, scaling settings, and more. For more information, see the app.yaml reference.

Creating the main.go file

This sample uses the net/http package to create an HTTP server that prints "Hello world".

To set up your main.go file:

  1. In your go-app/ folder, create a main.go file.

  2. Add the package main statement to treat your code as an executable program:

    package main

    To successfully deploy a service in the Go 1.11 runtime, a package main statement must be defined at the beginning of at least one of your Go source files in the same directory as your service's app.yaml file.

  3. Import the following packages:

    import (
  4. Define your HTTP handler:

    // indexHandler responds to requests with our greeting.
    func indexHandler(w http.ResponseWriter, r *http.Request) {
    	if r.URL.Path != "/" {
    		http.NotFound(w, r)
    	fmt.Fprint(w, "Hello, World!")

    The http.ResponseWriter object assembles the HTTP server response; by writing to it, you send data to the browser. The http.Request object is a data structure that represents the incoming HTTP request.

  5. Register your HTTP handler:

    func main() {
    	http.HandleFunc("/", indexHandler)
    	port := os.Getenv("PORT")
    	if port == "" {
    		port = "8080"
    		log.Printf("Defaulting to port %s", port)
    	log.Printf("Listening on port %s", port)
    	if err := http.ListenAndServe(":"+port, nil); err != nil {

    The main function is the entry point of your executable program, so it starts the application. It begins with a call to the http.HandleFunc function which tells the http package to handle all requests to the web root ("/") with the indexHandler function.

    If the PORT environment variable is not set, port 8080 is used as a default. When your app is running on App Engine, the PORT environment variable is set for you, but when testing your app locally, you can set PORT to any preferred value.

Deploying your web service on App Engine

  1. In your go-app directory where your app.yaml file is located, deploy your web service to App Engine using the following command:

    gcloud app deploy

  2. To launch your browser and view your web service at, run the following command:

    gcloud app browse

Congratulations! You've just created and deployed a service on App Engine.

Services and versions

The first service you deploy for your application will be the default service. You can specify the name of your service in the app.yaml file, but if the name is omitted, it is treated as default. You can deploy multiple services other than the default service.

You can update your service at any time by running the gcloud app deploy command. Each time you deploy, a new version is created and traffic is automatically routed to the latest version.

To confirm service creation and version deployment:

  1. View your App Engine services in the Google Cloud console:

    View services

    You should see one service listed, named default. The default service is publicly accessible at the following URL:

  2. View your versions:

    View versions

    You should see one timestamped version listed, corresponding to your deployment.

To learn how to send requests to specific services and versions, see How Requests are Routed.

Next steps

Congratulations! You just set up and deployed your web application to App Engine.

Learn how to add other features to your application by exploring the following pages: