Host your own Go playground
Switch branches/tags
Nothing to show
Clone or download
xiam Merge pull request #2 from jflory7/change/fix-docker
Fix Docker images (adds -allow-share to ENTRYPOINT)
Latest commit 1589678 Jul 30, 2017

README.md

Your own Go Playground

The Go Playground is a pretty good way to learn about Go programs without actually installing Go. You can set up identical playgrounds easily using the golang/playground repository at Github.

What's wrong with the Go Playground?

Nothing really. The official Go Playground runs on a sandbox, which is the recommended way of doing things like executing code from untrusted sources, since it minimizes the risk of crackers abusing the system.

However, if you ever need to showcase features that require network, a real filesystem, CGO or any kind of thing not supported or actively restricted by NaCL you will be out of luck.

This alternative playground offers you more flexibility on that front, you can choose when to use the sandbox and when not to.

So, this is like the Go Playground?

Yes, it's actually a fork of it. You can see a live example of this playground here: https://play.golang.mx. Note that this sandbox uses the official Go Playground compilation service, therefore the same restrictions apply to it.

Frontend (webapp)

The web app is the front end part of the playground, it can do a few tasks of its own like storing snippets or formatting code but it delegates the compilation to an external service.

This is similar to the play.golang.org web app, except that it:

  • Does not depend on appengine.
  • Uses boltdb to save data.
  • Can be configured to communicate with any other Go Playground service (the one that compiles and runs Go code), including the official one.

You can build and run a Go Playground like this:

cd webapp
go build
./webapp -allow-share
# 2016/01/03 08:26:23 Serving Go playground at :3000...

This will create a local server that uses the official Go Playground service to build and run Go code. See the main page at http://127.0.0.1:3000.

screen shot 2016-01-03 at 8 12 25 am

Love those nice live examples on the golang.org site? You can also embed them in your website using a few lines of code:

screen shot 2016-01-03 at 8 12 50 am

See a local example at http://127.0.0.1:3000/example or a live one at https://play.golang.mx/example.

If you're into Docker you can create and run a container like this:

cd webapp
make docker-build
make docker-run

See the available commands with -h:

./webapp -h
  -allow-share
        Allow storing and sharing snippets.
  -db string
        Database file. (default "playground.db")
  -disable-cache
        Disable cache.
  -h    Show help.
  -l string
        Listen address. (default ":3000")
  -o string
        Access-Control-Allow-Origin header. (default "*")
  -s string
        Sandbox service URL. (default "https://play.golang.org/compile?output=json")

Too complicated, I just came here for the live examples

If you're only interested on embedding Go examples that run on the official Go Playground sandbox you can start coding something based on this snippet which just works:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />

    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>

    <link href="//play.golang.mx/static/example.css" rel="stylesheet" type="text/css" />
    <link href="//play.golang.mx/static/codemirror.css" rel="stylesheet" type="text/css" />

    <script src="//play.golang.mx/static/playground-full.js"></script>
    <script src="//play.golang.mx/static/snippets.js"></script>

    <script>
    goPlaygroundOptions({
      'shareRedirect': '//play.golang.mx/p/',
      'shareURL': '//play.golang.mx/share',
      'compileURL': '//play.golang.mx/compile',
      'fmtURL': '//play.golang.mx/fmt',
      'shareOpenNewWindow': true
    });
    </script>
  </head>
  <body>
    <textarea class="go-playground-snippet" data-title="Example (Hello Playground!)">
package main

import (
&#09;"fmt"
)

func main() {
&#09;fmt.Printf("Hello Playground!")
}</textarea>
  </body>
</html>

It's OK to hotlink, but don't rely on it being available 24/7.

Compilation services

sandbox

If you don't want to use the Go Playground service for building and running Go code you can also run your own service.

This sandbox is based on the original sandbox, it includes the same restrictions we have in the original (NaCL, no network access, no real filesystem, fake time, etc.).

The main difference is in this handler that now accepts form-data as well as JSON formatted data.

Build and run the sandbox like this:

cd sandbox
make docker
make run

You can point the Go Playground web app to this service using the -s parameter:

cd webapp
./webapp -allow-share -s "http://localhost:8080/compile?output=json"

unsafebox

I basically took out all the security measures of the original sandbox and now I offer you a dumbed down version of it which actually does not sandbox anything and will put your life at risk.

This is a unrestricted linux/amd64 installation, you should not really use this box unless you're absolutely sure you know what you're doing and you're aware that no matter what you do, people will try to abuse the system and they will probably succeed.

Ok, now that you're warned, you can (but shouldn't) build and run this dangerous box like this:

cd unsafebox
make docker
make run

You can point the Go Playground web app to this service using the -s parameter:

cd webapp
./webapp -allow-share -s "http://localhost:8080/compile?output=json"

Welcome to the world of remote code execution!

Remember that this machine is completely open to the world, if you plan to upload it to a public place you should take some other containment measures, such as not using root to run the sandbox, using chroot jails and iptables rules, etc. this really depends on your specific needs.

Importing custom packages

Remember that playground users won't be able to install or use packages that are not part of the Go standard library, in case you want to showcase a special package you'll have to create a slightly different docker image on top of the sandbox or the unsafebox, see this Dockerfile:

FROM xiam/go-playground/unsafebox

RUN go get github.com/myuser/mypackage
RUN go get github.com/otheruser/otherpackage

ENTRYPOINT ["/go/bin/sandbox"]

You can build that docker image and then start webapp using the -s parameter pointing to the docker image and you'll be able to import custom packages from your playground:

./webapp -disable-cache -s "http://custom.box/compile?output=json"

screen shot 2016-01-03 at 2 32 00 pm

Feel free to use this playground on your next workshop to demonstrate your Go projects to others ;-)