Go Runtime Environment

Welcome to Google App Engine for Go. With App Engine, you can build web applications using the Go Programming Language. Your Go application runs on Google's scalable infrastructure and uses large-scale persistent storage and services.

1. Introduction
2. Selecting the Go runtime
3. Organizing Go apps
4. The sandbox
5. The Go SDK and tools

Introduction

App Engine builds and executes Go application code using a safe "sandboxed" environment. Your app receives web requests, performs work, and sends responses by interacting with this environment.

The Go SDK provides an interface similar to the standard Go http package; writing Go App Engine apps is akin to writing stand-alone Go web servers.

The Go runtime environment uses Go version 1.4. The SDK includes the Go compiler and standard library, so it has no additional dependencies. As with the other runtimes, not all the standard library's functionality is available inside the sandbox. For example, attempts to open a socket or write to a file will return an os.ErrPermission error.

The SDK includes an automated build service to compile your app, so you'll never need to invoke the compiler yourself. And—as with the Python SDK—your app will be automatically re-built whenever you change the source.

The Go runtime environment for App Engine provides full support for goroutines, but not for parallel execution: goroutines are scheduled onto a single operating system thread. This single-thread restriction may be lifted in future versions. Multiple requests may be handled concurrently by a given instance; that means that if one request is, say, waiting for a datastore API call, another request may be processed by the same instance.

Go apps run inside a secure "sandbox" environment with a reduced set of libraries. For instance, an app cannot write data to the local file system or make arbitrary network connections. Instead, apps use scalable services provided by App Engine to store data and communicate over the Internet.

The App Engine platform provides many services that your code can call.

If you haven't already, see the Go Getting Started Guide for an introduction to developing web applications with Go and Google App Engine.

Selecting the Go runtime

App Engine knows to use the Go runtime environment for your application code when you use the tool named appcfg.py from the Go SDK with a configuration file named app.yaml. You select the Go runtime environment using the following configuration elements:

runtime: go
api_version: go1

The first element, runtime, selects the Go runtime environment.

The second element, api_version, selects which version of the Go runtime environment to use. As of this writing, the most recent version of the Go environment is go1. The version identifier will be incremented when the App Engine team releases changes to the environment that may not be compatible with existing code. This means you can continue to use the older APIs until you are able to update your app and change the api_version setting.

Organizing Go apps

When developing an App Engine app in Go, your code is partitioned into one or more modules; each module is usually contained in its own directory, along with an app.yaml file for the module:

- project-dir
   - module1-dir
      app.yaml
      src1-1.go
      src1-2.go
   - module2-dir
      app.yaml
      src2-1.go
      src2-2.go

Go applications are organized into packages that mirror the directory structure of your source files. When you use an import statement in App Engine source code, the SDK tools interpret the relative paths in the import two ways:

• Relative to the directory that contains the module's app.yaml file

• Relative to the src subdirectory of all the directories in GOPATH (this is called a "fully-qualifed" import path)

For example, if GOPATH is defined this way:

export GOPATH=/home/fred/go

And the file src1-1.go in the project directory example above contains this statement:

import "foo/bar"

The SDK will look for the package "foo/bar" in these locations when you run or deploy module1:

project-dir/module1/foo/bar
/home/fred/go/src/foo/bar

If you include your package sources in GOPATH, you must be careful not to place the source code at or below any directories in your App Engine project that contain app.yaml files. If that happens, a package could be loaded twice, once for the path relative to a module's directory, and once for the fully-qualified path. This can cause subtle problems, so the Go SDK scans your project and your GOPATH, detects this case, and reports it as an error.

For best results, we recommend:

• Create a separate directory in your project for each module.
• Each module directory should contain the module's app.yaml file and one or more .go files.
• Do not include any subdirectories in a module's directory.
• Your .go files should import packages using fully-qualified paths; place all package code beneath src directories that are direct children of the project directory, or not under your project directory at all.

For more information about the structuring of Go modules, see Go Module Configuration.

For an introduction to Go's GOPATH and how it relates to App Engine development, please see The App Engine SDK and workspaces.

The sandbox

To allow App Engine to distribute requests for applications across multiple web servers, and to prevent one application from interfering with another, the application runs in a restricted "sandbox" environment. In this environment, the application can execute code, store and query data in the App Engine datastore, use the App Engine mail, URL fetch and users services, and examine the user's web request and prepare the response.

An App Engine application cannot:

• write to the filesystem. Applications must use the App Engine datastore for storing persistent data. Reading from the filesystem is allowed, and all application files uploaded with the application are available.

• respond slowly. A web request to an application must be handled within a few seconds. Processes that take a very long time to respond are terminated to avoid overloading the web server.

• make other kinds of system calls.

The Go runtime restricts the use of standard library packages that would violate the sandbox policies. Such functions have been replaced by stubs that return an os.ErrPermission error or removed entirely.

The Go SDK and tools

The App Engine Go SDK includes tools for testing your application and uploading application files.

The development server runs your application on your local computer for testing your application. The server simulates the App Engine Datastore, services and sandbox restrictions. The development server can also generate configuration for Datastore indices based on the queries the app performs during testing.

A multipurpose tool called appcfg.py handles all command-line interaction with your application running on App Engine. The appcfg.py tool can upload your application to App Engine, or just update the datastore index configuration so you can build new indexes before updating the code. It can also download the app's log data, so you can analyze your app's performance using your own tools.

The tools used for locally serving apps (goapp serve) and for deploying to App Engine production (goapp deploy) are typically invoked from within the Go app's root directory. Alternatively, the application root directory can be added to these commands or a list of the full or relative paths to the yaml file(s) of the app can be specified. Run goapp help serve or goapp help deploy for more information about these commands.

The SDK also includes some tools from the Go tool chain:

Godoc extracts and generates documentation for Go programs. Godoc uses the source code of the Go standard library and Go App Engine SDK that is included in the SDK zip file.

Gofmt formats Go programs.