tree: 190cb422e922ce6abc65ff23188c66ed47ba6161 [path history] [tgz]
  1. builder/
  2. compilerd/
  3. config/
  4. lib/
  5. migrations/
  6. testdata/
  7. .gitignore
  8. Dockerfile
  9. dummy.go
  10. Makefile
  11. README.md
  12. sql_test_setup.sh
go/src/v.io/x/playground/README.md

Building a Docker image and running the playground server locally

Docker setup

Install Docker:

On Goobuntu, we recommend overriding the default graph dir (/var/lib/docker) to avoid filling up the root filesystem partition, which is quite small. To do so, add the following line to your /etc/default/docker:

DOCKER_OPTS="${DOCKER_OPTS} -g /usr/local/google/docker"

Add your user to the docker group:

$ sudo usermod -a -G docker $(whoami)

Start (or restart) the Docker daemon:

$ sudo service docker restart

Build the playground Docker image (this will take a while...):

$ cp ~/.netrc $V23_ROOT/release/projects/playground/go/src/v.io/x/playground/netrc
$ docker build -t playground $V23_ROOT/release/projects/playground/go/src/v.io/x/playground/.

Note: If you want to ensure an up-to-date version of Vanadium is installed in the Docker image, run the above command with the “--no-cache” flag.

Note: If you have only a .gitcookies googlesource.com entry and not a .netrc one, you can convert it to a .netrc entry using:

$ cat ~/.gitcookies | grep vanadium.googlesource.com | tail -n 1 | sed -E 's/(\S+)\s+(\S+\s+){5}([^=]+)=(\S+)/machine \1 login \3 password \4/' >> ~/.netrc

(see http://www.chromium.org/chromium-os/developer-guide/gerrit-guide for details)

The ‘docker build’ command above will compile builder from the main Vanadium repository. If you want to use local code instead, open Dockerfile and uncomment marked lines before running the command.

Test your image (without running compilerd):

$ cd $V23_ROOT/release/projects/playground/client && make src/example_bundles
$ docker run -i playground < $V23_ROOT/release/projects/playground/client/bundles/fortune/bundle_js_go.json

Running the playground server (compilerd)

Install the playground binaries:

$ GOPATH=$V23_ROOT/release/projects/playground/go v23 go install v.io/x/playground/...

Run the compiler binary:

$ $V23_ROOT/release/projects/playground/go/bin/compilerd --listen-timeout=0 --address=localhost:8181

Or, run it without Docker (for faster iterations during development):

$ PATH=$V23_ROOT/release/go/bin:$V23_ROOT/release/projects/playground/go/bin:$PATH compilerd --listen-timeout=0 --address=localhost:8181 --use-docker=false

The server should now be running at http://localhost:8181 and responding to compile requests at http://localhost:8181/compile.

Add ?pgaddr=http://localhost:8181 to any playground page on localhost to make the client talk to your server. Add ?debug=1 to see debug info from the builder.

Running local SQL database

NOTE: These instructions should only be used for local development and testing, and not for production deploys.

Install MariaDB:

$ sudo apt-get install mariadb-server

Sign in to Maria as root:

$ mysql -u root -p

Create playground databases:

MariaDB [(none)]> CREATE DATABASE IF NOT EXISTS playground;

Create a playground user who has access to the playground database:

MariaDB [(none)]> GRANT ALL PRIVILEGES ON playground.* TO 'playground'@'localhost';

Create config/db.json from example:

$ cp config/db-local-example.json config/db.json

Edit config/db.json and set username, password, and database.

TODO(ivanpi): Describe cloud storage.

Running tests

Make sure you have built a docker playground image, following the steps above.

Make sure that MariaDB is installed, following the steps above.

Run sql_test_setup.sh. You will be prompted for your MariaDB password for root account. You only need to do this once.

$ ./sql_test_setup.sh

This script will create a playground_test database, and a playground_test user that can access it.

Run the tests:

$ GOPATH=$V23_ROOT/release/projects/playground/go v23 go test v.io/x/playground/compilerd/...

Database migrations

Running migrations

Build the sql-migrate tool:

$ v23 go install github.com/rubenv/sql-migrate/sql-migrate

Edit config/migrate.yml. Find or define whatever environment you plan to migrate, and make sure the datasource is correct.

To see the current migration status, run:

$ $V23_ROOT/third_party/go/bin/sql-migrate status -config=./config/migrate.yml -env=<environment>

To migrate up, first run with -dryrun:

$ $V23_ROOT/third_party/go/bin/sql-migrate up -config=./config/migrate.yml -env=<environment> -dryrun

If everything looks good, run the tool without -dryrun:

$ $V23_ROOT/third_party/go/bin/sql-migrate up -config=./config/migrate.yml -env=<environment>

You can undo the last migration with:

$ $V23_ROOT/third_party/go/bin/sql-migrate down -limit=1 -config=./config/migrate.yml -env=<environment>

For more options and infomation, see https://github.com/rubenv/sql-migrate#usage

Writing migrations

Migrations are kept in the migrations directory. They are ordered alphabetically, so please name each migration consecutively. Never delete or modify an existing migration. Only add new ones.

Each migration file must define an “up” section, which begins with the comment

-- +migrate Up

and a “down” section, which begins with the comment

-- +migrate Down

Applying a single migration “up” and then “down” should leave the database in the same state it was to begin with.

For more information on writing migrations, see https://github.com/rubenv/sql-migrate#writing-migrations