Go tutorial and reference

docs/reference/extensions/go-framework.rst

@@ -0,0 +1,71 @@
+.. _go-framework-reference:
+
+go-framework
+----------------
+
+The Go extension streamlines the process of building Go application
+rocks.
+
+The extension builds and copies the Go binary file to the rock,
+inside the ``/app`` directory. By default, the base ``bare`` is used,
+that generates a lightweight image.
+
+
+.. note::
+    The Go extension is compatible with the ``bare`` and ``[email protected]``
+    bases.
+
+Project requirements
+====================
+
+To use the ``go-framework`` extension, there must be a ``go.mod`` file
+in the root directory of the project.
+
+
+``parts`` > ``go-framework/install-app`` > ``organize``
+=========================================================
+
+If the main package is in the base directory and the rockcraft name
+attribute is equal to the go module name, the name of the binary will
+be selected correctly, otherwise you can adjust it.
+
+You can use this field to specify a different binary to be used as the
+main application, without having to override the service command. For example,
+if your Go application container a ``main`` package in the directory
+``cmd/anotherserver``, the name of the binary will be ``anotherserver``
+and you can override the main application to use the binary with the
+next snippet:
+
+.. code-block:: yaml
+
+  parts:
+    go-framework/install-app:
+     organize:
+       bin/anotherserver: usr/local/bin/<rockcraft project name>
+
+
+``parts`` > ``go-framework/assets`` > ``assets``
+=========================================================
+
+
+Some files, if they exist, are included by default. These include:
+``migrate``, ``migrate.sh``, ``templates/`` and ``static/``.
+
+You can customise the files to include overriding the ``stage`` property
+of the ``go-framework/assets`` part:
+
+.. code-block:: yaml
+
+  parts:
+    go-framework/assets:
+      stage:
+        - app/migrate
+        - app/migrate.sh
+        - app/static
+        - app/another_file_or_directory
+
+
+Useful links
+============
+
+- :ref:`build-a-rock-for-a-go-application`

docs/reference/extensions/index.rst

@@ -13,3 +13,4 @@ initiating a new rock.
 
    flask-framework
    django-framework
+   go-framework

docs/reference/rockcraft.yaml.rst

@@ -263,6 +263,9 @@ Extensions to enable when building the ROCK.
 Currently supported extensions:
 
 - ``flask-framework``
+- ``django-framework``
+- ``go-framework``
+- ``fastapi-framework``
 
 Example
 =======

docs/tutorial/code/go/anotherserver_part

@@ -0,0 +1,4 @@
+parts:
+  go-framework/install-app:
+    organize:
+       bin/anotherserver: usr/local/bin/go-hello-world

docs/tutorial/code/go/cmd/anotherserver/main.go

@@ -0,0 +1,18 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+)
+
+func helloWorld(w http.ResponseWriter, req *http.Request) {
+	log.Printf("anotherserver hello world request")
+	fmt.Fprintf(w, "Hello World from anotherserver")
+}
+
+func main() {
+	log.Printf("starting anotherserver hello world application")
+	http.HandleFunc("/", helloWorld)
+	http.ListenAndServe(":8000", nil)
+}

docs/tutorial/code/go/main.go

@@ -0,0 +1,18 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+)
+
+func helloWorld(w http.ResponseWriter, req *http.Request) {
+	log.Printf("new hello world request")
+	fmt.Fprintf(w, "Hello World")
+}
+
+func main() {
+	log.Printf("starting hello world application")
+	http.HandleFunc("/", helloWorld)
+	http.ListenAndServe(":8000", nil)
+}

docs/tutorial/code/go/task.yaml

@@ -0,0 +1,109 @@
+###########################################
+# IMPORTANT
+# Comments matter!
+# The docs use the wrapping comments as
+# markers for including said instructions
+# as snippets in the docs.
+###########################################
+summary: Getting started with Go tutorial
+
+environment:
+
+execute: |
+  set -x
+  # [docs:install-go]
+  sudo snap install go --classic
+  # [docs:install-go-end]
+
+  # [docs:mod-init-go]
+  go mod init go-hello-world
+  go mod tidy
+  # [docs:mod-init-go-end]
+
+  # [docs:go-build]
+  go build .
+  # [docs:go-build-end]
+
+  ./go-hello-world &
+  retry -n 5 --wait 2 curl localhost:8000
+
+  # [docs:curl-go]
+  curl localhost:8000
+  # [docs:curl-go-end]
+
+  kill $!
+
+  # [docs:create-rockcraft-yaml]
+  rockcraft init --profile go-framework
+  # [docs:create-rockcraft-yaml-end]
+  sed -i "s/name: .*/name: go-hello-world/g" rockcraft.yaml
+
+  # [docs:pack]
+  ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true rockcraft pack
+  # [docs:pack-end]
+
+  # [docs:ls-rock]
+  ls *.rock -l --block-size=MB
+  # [docs:ls-rock-end]
+
+  # [docs:skopeo-copy]
+  sudo rockcraft.skopeo --insecure-policy \
+    copy oci-archive:go-hello-world_0.1_amd64.rock \
+    docker-daemon:go-hello-world:0.1
+  # [docs:skopeo-copy-end]
+
+  # [docs:docker-images]
+  sudo docker images go-hello-world:0.1
+  # [docs:docker-images-end]
+
+  # [docs:docker-run]
+  sudo docker run --rm -d -p 8000:8000 \
+    --name go-hello-world go-hello-world:0.1
+  # [docs:docker-run-end]
+
+  retry -n 5 --wait 2 curl localhost:8000
+  # [docs:curl-go-rock]
+  curl localhost:8000
+  # [docs:curl-go-rock-end]
+  [ "$(curl localhost:8000)" = "Hello World" ]
+
+  # [docs:get-logs]
+  sudo docker exec go-hello-world pebble logs go
+  # [docs:get-logs-end]
+
+  # [docs:stop-docker]
+  sudo docker stop go-hello-world
+  sudo docker rmi go-hello-world:0.1
+  # [docs:stop-docker-end]
+
+  ## Part 2 of the tutorial
+  sed -i "s/version: .*/version: 0.2/g" rockcraft.yaml
+  cat anotherserver_part >> rockcraft.yaml
+
+  # [docs:docker-run-update]
+  ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true rockcraft pack
+  sudo rockcraft.skopeo --insecure-policy \
+    copy oci-archive:go-hello-world_0.2_amd64.rock \
+    docker-daemon:go-hello-world:0.2
+  sudo docker images go-hello-world:0.2
+  sudo docker run --rm -d -p 8000:8000 \
+    --name go-hello-world go-hello-world:0.2
+  # [docs:docker-run-update-end]
+  retry -n 5 --wait 2 curl localhost:8000
+
+  # [docs:curl-anotherserver]
+  curl localhost:8000
+  # [docs:curl-anotherserver-end]
+  [ "$(curl localhost:8000)" = "Hello World from anotherserver" ]
+
+  # [docs:stop-docker-updated]
+  sudo docker stop go-hello-world
+  sudo docker rmi go-hello-world:0.2
+  # [docs:stop-docker-updated-end]
+
+  # [docs:cleanup]
+  # delete all the files created during the tutorial
+  rm go.mod rockcraft.yaml main.go go-hello-world \
+    go-hello-world_0.1_amd64.rock \
+    go-hello-world_0.2_amd64.rock
+  # [docs:cleanup-end]