Upsun User Documentation

Go

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
¹Terms and conditions apply
Activate your 15-day trial

Upsun supports building and deploying applications written in Go using Go modules. They’re compiled during the Build hook phase, and support both committed dependencies and download-on-demand.

Supported versions Anchor to this heading

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.

  • 1.23
  • 1.22
  • 1.21
  • 1.20

Specify the language Anchor to this heading

To use Go, specify golang as your app’s type:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    <APP_NAME>:
        type: 'golang:<VERSION_NUMBER>'

For example:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'golang:1.23'

Deprecated versions Anchor to this heading

The following versions are deprecated. They’re available, but they aren’t receiving security updates from upstream and aren’t guaranteed to work. They’ll be removed in the future, so migrate to one of the supported versions.

  • 1.19
  • 1.18
  • 1.17
  • 1.16
  • 1.15
  • 1.14
  • 1.13
  • 1.12
  • 1.11
  • 1.10
  • 1.9
  • 1.8

Go modules Anchor to this heading

The recommended way to handle Go dependencies on Upsun is using Go module support in Go 1.11 and later. That allows the build process to use go build directly without any extra steps, and you can specify an output executable file of your choice. (See the examples below.)

Building and running the application Anchor to this heading

Assuming your go.mod and go.sum files are present in your repository, your application can be built with the command go build, to produce a working executable. You can then start it from the web.commands.start directive. Note that the start command must run in the foreground. If the program terminates for any reason it is automatically restarted.

The following basic .upsun/config.yaml file is sufficient to run most Go applications.

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'golang:1.23'

        hooks:
            build: |
                # Modify this line if you want to build differently or
                # use an alternate name for your executable.
                go build -o bin/app                

        web:
            upstream:
                socket_family: tcp
                protocol: http

            commands:
                # If you change the build output in the build hook above, update this line as well.
                start: ./bin/app

            locations:
                /:
                    # Route all requests to the Go app, unconditionally.
                    allow: false
                    passthru: true

Note that there is still an Nginx proxy server sitting in front of your application. If desired, certain paths may be served directly by Nginx without hitting your application (for static files, primarily) or you may route all requests to the Go application unconditionally, as in the example above.

Accessing services Anchor to this heading

To access various services with Go, see the following examples. The individual service pages have more information on configuring each service.

You can access service credentials to connect to managed services from environment variables present in the application container. Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

Is this page helpful?