Au revoir to templates: Go on Upsun

The story of templates (so far)

I've worked at Platform.sh - and as a part of the DevRel team here - for five years now. It's a great team to be a part of, especially because it allows for the space to switch between new experiments all the time. You could come to work on Monday, have a user ask about a programming language you'd never played with on Tuesday, and by Friday you will have figured how to deploy that language, a new framework, and hopefully shared what you had learned with a new template. 

For a long time, this cycle was a big part of our DevRel work. It's been a wonderful way of transforming community feedback into knowledge others could work with, but as you can imagine as the years went by more and more effort needed to be placed into maintaining these examples.

That in itself, has been interesting work, leading into its own investigations into scheduling automatic updates with source operations to coordinating and syncing updates across repositories using GitHub actions. Yet, the problem is larger than scope of what how we as a team would prefer to spend our time.

That is - it's working with users to solve their problems, experimenting together to find a solution, that's the important bit - rather than maintaining hundreds of one-off examples forever.

And the newest update! The upcoming general release of our new offering Upsun! While many aspects of Upsun are identical to Platform.sh, there remain differences that could make up a whole new organization of templates…. I can see the boulder now, rolling down the track towards me.

So, in short, we're going to be making some changes as a team as to how we handle our templates/public example repos. Namely:

• We will drastically reduce the number of templates that remain in our Platform.sh catalog during onboarding.
• Upsun will not have a templates catalog
• We will move examples into the main platformsh organization
• We will replicate the knowledge we've gained from these examples into archived repos (first at github.com/platformsh, then at github.com/upsun)

Templates and examples will be associated with a blog post - an experiment at that point in time. They'll be made available publicly, but more likely than not, will be archived that same day. We hope that they continue to be useful as reference material, but we'd really like our team (and you!) to spend more time experimenting than maintaining what was always meant to be fun learning resources.

On my part, I'll do my best to tackle at least one of these templates each week, and document the process here, so that hopefully you get a better idea of what was test, changed, and discovered along the way.

Getting started with Go

I remember in my first year at Platform.sh - so wide-eyed and fresh, knowing only a little Python - being told that I should make a whole bunch of templates in Go. Something I knew nothing about (both Go specifically and statically typed languages). 

One of the first was a simple “Hello world” Go example, something that presented an index page to the user and a quick test to a MariaDB database.

Updates for Platform.sh

So, to start off, I:

1. Moved the Platform.sh configuration to a .platform/applications.yaml file, under a top-level key app. I also updated to the most recent Go 1.22 and downloaded that locally. 

app:
    type: golang:1.22
    hooks:
        build: |
            go build -o bin/app
    relationships:
        database: "db:mysql"
    web:
        upstream:
            socket_family: tcp
            protocol: http
        commands:
            start: ./bin/app
        locations:
            /:
                allow: false
                passthru: true
    disk: 1024

I also updated to a more recent version of MariaDB in the .platform/services.yaml file:

db:
    type: mariadb:11.2
    disk: 1024

2. After updating the Go version constraint in go.mod to go 1.22.1, I ran a go get -u and go mod tidy to update and prune modules.

module github.com/platformsh/golang

require github.com/go-sql-driver/mysql v1.8.0

require filippo.io/edwards25519 v1.1.0 // indirect

go 1.22.1

This also was the first template to leverage our Go Configuration Reader library. With Upsun, however, I'd really like to recommend the config-reader library less these days. Upsun introduced automatic environment variable creation, which makes most of what the library did redundant. 

After creating a Platform.sh project to test this, I could open a tunnel (platform tunnel:open -y) to connect to the created service and mock credentials locally:

export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

I can also mimick the generated variables that would appear on Upsun for Platform.sh with a new start command and jq: 

        commands:
            # If you change the build output in the build hook above, update this line as well.
            start: |
                export DATABASE_USERNAME=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].username')
                export DATABASE_PASSWORD=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].password')
                export DATABASE_HOST=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].host')
                export DATABASE_PORT=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].port')
                export DATABASE_PATH=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].path')
                ./bin/app

Finally, we can strip down to a simplified Hello world script called in a server.go file. The file is too long to paste in this post, but you can find it here. You will notice that this file will work for both Platform.sh and Upsun. 

Since we've already opened the tunnel, we can run this locally to test:

$ source .environment && go build -o bin/app
$ ./bin/app

We can view the site at localhost:8000 , and give it one final test on Platform.sh (platform push).

All the configuration for the project on Platform.sh can be found for:

• the application
• the routes
• the services

And now for something completely different: Upsun

To move this now updated project to Upsun, we need to:

1. Create a new project with upsun project:create
2. Combine configuration into a single .upsun/config.yaml file
3. Remove or update outdated keys, such as disk and mounts

The final (and simplified) file can be found here.

applications:
    app:
        type: golang:1.22
        # stack:
        #   - "golang@1.22"
        hooks:
            build: |
                go build -o bin/app
        relationships:
            database:
        web:
            upstream:
                socket_family: tcp
                protocol: http
            commands:
                start: ./bin/app
            locations:
                /:
                    allow: false
                    passthru: true

services:
    database:
        type: mariadb:11.2

One template down (find the full repo at https://github.com/platformsh/golang , many more to go! Stay tuned for more Upsun migrations to come.

- Chad C.