naphthalene / gdlk

GDLK is a web-based puzzle game based on an assembly-like programming language.

GDLK

About

GDLK is a programming language, as well as a game based on solving puzzles with the language. There is no usable product yet, but it's coming soon™!

What does GDLK stand for?

GDLK Development Language Kit

Wait, but, what does GDLK stand for?

GDLK Development Language Kit!

Development

Setup

First, you'll need to install:

• docker-compose
• rustup

Then, for development you'll probably want to install more stuff:

rustup component add rustfmt-preview clippy-preview
cargo install diesel_cli --no-default-features --features postgres
cargo install cargo-make

Compiling and Executing Locally

If you just want to compile and run a program without starting up the webserver, you can use the CLI for that. To execute a program, you will need:

• A hardware spec, which defines what hardware the program can access (JSON)
• A program spec, which defines the input and expected output (JSON)
• A source file (GDLK)

See core/src/models.rs for a list of fields that the hardware and program specs need. Then, you can run the program with:

cargo run -p gdlk_cli -- run --hardware hw.json --program prog.json -s prog.gdlk

Running the Web Stack

In the repo root, run:

cd api && cargo make secrets && cd.. # Only needed on first execution
# Enter your username and the new token as your password
docker-compose up

Then, see the next section to initialize the DB.

Migrations & Seed Data

Migrations are managed by Diesel. Seed data is defined via SQL scripts, in api/seeds.

cd api
# Migrations are automatically run on server startup, but if you need to run them manually:
cargo make diesel migration run

# You can load seed data with:
cargo make seed

# If you need to re-run migrations (this will wipe out your DB!)
cargo make diesel db reset

Tests

You can run tests with:

cargo make test # In the root, or any sub-crate

Note: for API tests, you will need the database running. You can do this with either of these commands:

docker-compose up
# OR
docker-compose run --service-ports db

Debugging

If you have a GDLK program or test failing, you can have the GDLK compiler and interpreter output additional debug information by setting DEBUG=1.

DEBUG=1 cargo run -p gdlk_cli -- --hardware hw.json --program prog.json -s prog.gdlk
DEBUG=1 cargo make test

Nightly Rust

We use nightly Rust. Here's a list of reasons why. If this list every gets empty, we should switch to stable.

• Rust features
  • or_patterns
• Rustfmt
  • merge_imports
  • wrap_comments

Here's a helpful site for finding new nightly versions.

Deployment

This project is deployed through docker-machine on Google Cloud. Production images are built automatically on each merge to master, then those get deployed by manually running a command.

Testing deployment

You can test the production stack locally, or initialize a new one, like so:

• Make sure the values in deploy/dev.env are correct for you
  • Change GDLK_HOSTNAME to another address (preferably one that is listed under the OpenID clients)
    • You may need to add this to /etc/hosts to make it point at your development machine
  • Change GDLK_DOCKER_TAG if you're going to be pushing different versions of images.
• Run this:

cd deploy
cargo make deploy
# Fill in the secrets as necessary

Production deployment

Set the production machine as your docker-machine target, then:

docker-machine ssh <machine name>
mkdir -p /var/log/gdlk/nginx
exit

# On your development machine
cd deploy
cargo make -p production deploy
# Fill in the secrets as necessary

DB Backup/Restore

The database is backed up automatically. To restore from a backup, exec into the db-backup container, then run:

gsutil cp gs://<bucket>/<backup file> .
tar xzvf <backup file>
PGPASSWORD=$(cat $POSTGRES_PASSWORD_FILE) psql -h $POSTGRES_HOST -U $POSTGRES_USER -c "CREATE DATABASE gdlk;" # If necessary
PGPASSWORD=$(cat $POSTGRES_PASSWORD_FILE) psql -h $POSTGRES_HOST -U $POSTGRES_USER gdlk < backups/gdlk.bak