AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)
AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Using the AWS Elastic Beanstalk Go Platform

You can use AWS Elastic Beanstalk to run, build, and configure Go-based applications.

Deploying Simple Go Applications

For simple Go applications, there are two ways to deploy your application:

  • Provide a source bundle with a source file at the root called application.go that contains the main package for your application. Elastic Beanstalk builds the binary using the following command:

    go build -o bin/application application.go

    After the application is built, Elastic Beanstalk starts it on port 5000.

  • Provide a source bundle with a binary file called application. The binary file can be located either at the root of the source bundle or in the bin/ directory of the source bundle. If you place the application binary file in both locations, Elastic Beanstalk uses the file in the bin/ directory.

    Elastic Beanstalk launches this application on port 5000.

For more complex applications, you must use a Procfile, or a Procfile and a Buildfile.

Deploying Complex Go Applications

For more complex Go applications, there are two ways to deploy your application:

  • Provide a source bundle that includes your application source files, along with a Buildfile and a Procfile. The Buildfile includes a command to build the application, and the Procfile includes instructions to run the application.

  • Provide a source bundle that includes your application binary files, along with a Procfile. The Procfile includes instructions to run the application.

Creating a Build Configuration File (Buildfile)

To specify a custom build and configuration command for your Go application, include a file called Buildfile at the root of your source bundle. The file name is case sensitive. Use the following format for the Buildfile:

<process_name>: <command>

The command in your Buildfile must match the following regular expression: ^[A-Za-z0-9_]+:\s*.+$.

Elastic Beanstalk doesn't monitor the application that is run with a Buildfile. Use a Buildfile for commands that run for short periods and terminate after completing their tasks. For long-running application processes that should not exit, use the Procfile instead.

In the following example of a Buildfile, build.sh is a shell script that is located at the root of the source bundle:

make: ./build.sh

All paths in the Buildfile are relative to the root of the source bundle. If you know in advance where the files reside on the instance, you can include absolute paths in the Buildfile.

Creating an Application Process Configuration File (Procfile)

To specify custom commands to start a Go application, include a file called Procfile at the root of your source bundle. The file name is case sensitive. Use the following format for the Procfile:

<process_name>: <command>

Each line in your Procfile must conform to the following regular expression: ^[A-Za-z0-9_]+:\s*.+$.

Elastic Beanstalk expects processes run from the Procfile to run continuously. Elastic Beanstalk monitors these applications and restarts any process that terminates. For short-running processes, use a Buildfile command.

You can use any name for your Go application, as long as it conforms to the aforementioned regular expression. You must call the main application web.

web: bin/server
queue_process: bin/queue_processor
foo: bin/fooapp

Elastic Beanstalk exposes the main web application on the root URL of the environment; for example, http://my-go-env.elasticbeanstalk.com.

Elastic Beanstalk configures the nginx proxy to forward requests to your application on the port number specified in the PORT environment variable for your application. Your application should always listen on that port. You can access this variable within your application by calling the os.Getenv("PORT") method.

Elastic Beanstalk uses the port number specified in the PORT option setting for the port for the first application in the Procfile, and then increments the port number for each subsequent application in the Procfile by 100. If the PORT option is not set, Elastic Beanstalk uses 5000 for the initial port.

In the preceding example, the PORT environment variable for the web application is 5000, the queue_process application is 5100, and the foo application is 5200.

You can specify the initial port by setting the PORT option with the aws:elasticbeanstalk:application:environment namespace, as shown in the following example.

option_settings:
  - namespace:  aws:elasticbeanstalk:application:environment
    option_name:  PORT
    value:  <first_port_number>

For more information about setting environment variables for your application, see Option Settings.

Elastic Beanstalk also runs any application whose name does not have the web_ prefix, but these applications are not available from outside of your instance.

Standard output and error streams from processes started with a Procfile are captured in log files named after the process and stored in /var/log. For example, the web process in the preceding example generates logs named web-1.log and web-1.error.log for stdout and stderr, respectively.

All paths in the Procfile are relative to the root of the source bundle. If you know in advance where the files reside on the instance, you can include absolute paths in the Procfile.

Execution Order

For Go applications, the commands and configuration settings are executed in the following order:

  1. The commands in the .ebextensions directory of the source bundle.

  2. Buildfile commands. Elastic Beanstalk runs all commands concurrently.

  3. The container_commands in the .ebextensions directory of the source bundle.

  4. Procfile commands. Elastic Beanstalk runs all commands concurrently.

Setting Configuration Options

In addition to the options supported by all platforms, the Go platform provides an additional namespace for specifying folders that contain files that should be served statically by the proxy server.

For example, this configuration file tells the proxy server to serve files in the myimages folder at the path /images:

option_settings:
  aws:elasticbeanstalk:container:golang:staticfiles:
    /images: myimages

Configuring the Reverse Proxy

Elastic Beanstalk uses nginx as the reverse proxy to map your application to your load balancer on port 80. If you want to provide your own nginx configuration, you can override the default configuration provided by Elastic Beanstalk by including the .ebextensions/nginx/nginx.conf file in your source bundle. If this file is present, Elastic Beanstalk uses it in place of the default nginx configuration file.

If you want to include directives in addition to those in the nginx.conf http block, you can also provide additional configuration files in the .ebextensions/nginx/conf.d/ directory of your source bundle. All files in this directory must have the .conf extension.

To take advantage of functionality provided by Elastic Beanstalk, such as Enhanced Health Reporting and Monitoring, automatic application mappings, and static files, you must include the following line in the server block of your nginx configuration file:

include conf.d/elasticbeanstalk/*.conf;