Educational computer programming environment using Haskell
Clone or download
cdsmith Initial implementation of list-based color mixing.
This isn't switched over yet, but the implementation is in place for
when it is.  See #768
Latest commit cfe9134 Jan 6, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Simplify bug report template. Nov 27, 2018
codeworld-account JWT-based authentication using local SQLite3 database Jun 10, 2018
codeworld-api Initial implementation of list-based color mixing. Jan 7, 2019
codeworld-auth JWT-based authentication using local SQLite3 database Jun 10, 2018
codeworld-base typo Dec 11, 2018
codeworld-compiler Add matchesRegex rule. Jan 6, 2019
codeworld-error-sanitizer Detect pattern guards in preprocessing rather than GHC opts Dec 5, 2018
codeworld-game-api Remove redundant -O flags. Jul 20, 2018
codeworld-game-server Run hlint on all source files. Jan 14, 2018
codeworld-prediction Disable pattern guards in codeworld-mode. Sep 19, 2018
codeworld-server Implementation of pattern matching using TemplateHaskell splices. Jan 2, 2019
funblocks-client Change the `#` block to use the operator rather than the `at` function. Sep 20, 2018
ghc-artifacts Switch to -main-is for the main -> program conversion. Aug 22, 2017
third_party Roll back the change last summer to function highlighting. Oct 5, 2018
web Create a simple TOS Jan 4, 2019
.gitignore JWT-based authentication using local SQLite3 database Jun 10, 2018
.gitmodules Add missing submodule URL for Stefan's fork of Blockly Jun 20, 2016
AUTHORS Add some missing authors May 18, 2018
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Feb 26, 2018
CONTRIBUTING.md Update CONTRIBUTING.md Oct 26, 2016
CONTRIBUTORS Add chessai as an honorary contributor Oct 1, 2018
LICENSE Get some legal stuff in place for open source release. Jun 18, 2014
README.md Add stability comment about blocks UI Sep 21, 2018
RequirementChecker.md Update RequirementChecker.md Jan 3, 2019
ServerSetup.md Update ServerSetup.md Jun 12, 2018
Users.md Fix typo on string #17 Jan 2, 2019
base.sh fix(install): initialize color variables for non color capable terminals Sep 25, 2018
build.sh JWT-based authentication using local SQLite3 database Jun 10, 2018
inc-build-test.sh Partial work on incremental builds. Sep 3, 2017
install.sh JWT-based authentication using local SQLite3 database Jun 10, 2018
run.sh Reorganize files to separate source and build dirs. Jul 20, 2018
test.sh Add errorCheck server route. Sep 26, 2018

README.md

CodeWorld

CodeWorld is an educational environment using Haskell. It provides a simple mathematical model for geometric figures, animations, and interactive and multi-player games. The web-based programming environment supports this educational mission with a zero-setup editor and compiler, easy sharing and cloud storage of projects, and the ability to run programs right in the web browser using GHCJS.

There are several variants of CodeWorld available:

  • CodeWorld uses an educational variant of the Haskell language and libraries, designed to support mathematics instruction.
  • CodeWorld Haskell is built against standard Haskell instead of the educational variant, to build programs which can either be on the web site with GHCJS, or compiled natively with the codeworld-api package and blank-canvas.
  • CodeWorld Blocks provides a drag-and-drop programming user interface for younger students to build programs with CodeWorld. This interface still has some bugs, and isn't recommended for use.

Status

CodeWorld is stable and has been used in schools for years! See the users page for a partial list. We're constantly improving the environment, though. Breaking changes, when necessary, are scheduled to occur between typical (U.S.) K-12 school semesters, to minimize disruption of existing classes.

Google is distributing the code for CodeWorld, but CodeWorld is not an official Google project, and Google provides no support for it. Instead, questions about the project or code should be asked to the codeworld-discuss mailing list. A student-friendly question and answer forum is also available at http://help.code.world for questions about programs written using CodeWorld, rather than questions about building or modifying CodeWorld itself.

Getting Started

Just visit https://code.world to get started.

There is no need to download or install anything to use CodeWorld. This repository will be useful if you prefer to fork and modify the CodeWorld environment, or contribute changes.

Discuss and Learn More

To discuss and hear announcements about CodeWorld, subscribe to the mailing list at https://groups.google.com/forum/#!forum/codeworld-discuss

The mailing list should be used to:

  • Hear announcements about and discuss upcoming changes and features.
  • Ask questions about using the system, and give feedback about your experiences.
  • Share interesting ways of using the site, related classroom activities, and more.

To report bugs or file formal feature requests, try https://github.com/google/codeworld/issues.

Contributing

There is a slight bit of paperwork involved in contributing to CodeWorld. You'll need to agree to a Contributor License Agreement. See CONTRIBUTING.md for details.

Build and Deployment

Building and running CodeWorld can be a lengthy process, but is automated using the installation scripts in the root directory, which work on most forms of Linux, including Debian, Ubuntu, RedHat, and CentOS. The step by step instructions are as follows:

  1. Read the caveats, explained below.
  2. Change to the root directory of the project.
  3. Run ./install.sh to set up the project.
  4. Run ./run.sh to start the server.

You can now access the CodeWorld system at http://localhost:8080.

If you make changes to CodeWorld, you can rebuild it without rebuilding the dependencies:

  1. Change to the root directory of the project.
  2. Run ./build.sh to recompile just CodeWorld itself, using previously installed tools and libraries.
  3. Run ./run.sh to start the server.

Caveats

Leaky GHCJS Sandboxing

While the installation process installs most of its files inside codeworld/build, it does clobber ~/.ghc, ~/.ghcjs, and ~/.cabal. I recommend that you run CodeWorld as a dedicated user account to avoid causing problems for other Haskell installations. If you don't, note that you will lose your user package database.

See bug #4 for details.

Authentication

CodeWorld offers two modes of authentication or the ability to run with authentication disabled with reduced functionality. The two methods provided are as follows:

  • Google authentication: this method uses the Google API and Google accounts and is the mode of authentication enabled in the live CodeWorld site; this allows CodeWorld to offload account and credential management to a third party
  • Local authentication: this method uses a simple local database of account information and JWT-based stateless authentication in the browser; this is useful for applications where minimal external dependencies is required

Running CodeWorld in one of these two modes allows users to save and manage their projects and folders. With no authentication enabled, users are able to write, build and run code but lose the ability to save and manage projects and folders.

Google authentication

For Google authentication to work, you will need to obtain a Google API key and store it in web/clientId.txt.

To get a Google API key for your CodeWorld installation, please consult the following resources:

Once you have a Google API key, copy and paste it into web/clientId.txt. A running CodeWorld instance will immediately pick up changes to this file.

In general, the Google authentication system will be the easiest system to maintain since no local password stores are required. This is the mechanism used by the official, live version of CodeWorld.

Local authentication

For applications in which external dependencies, such as Google accounts, are not acceptable, we provide a simple local authentication system:

  • Uses a SQLite3 database
  • Uses good security practices by storing only BCrypt hashes of passwords
  • Uses JWT-based stateless authentication

This provides a local authentication system with very similar workflows to Google authentication (i.e. stateless client-side sessions). Currently, no web-based administrative interface is provided. Instead, you can use the codeworld-auth CLI tool to manage accounts.

The local authentication system may be useful for situations where an instructor cannot reasonably expect all students to have a valid Google account and in which the instructor is willing to deploy a local CodeWorld stack.

Create account database

Local authentication will be enabled if a codeworld-auth.db file is present in the application's root directory. To create this database, run the following from the root of the Git repository:

build/bin/codeworld-auth init-accounts -d codeworld-auth.db

This will create an empty account database with no accounts.

Create one or more user accounts

Assuming you have already created an account database as described above, you can create a new account as follows:

build/bin/codeworld-auth create-account -d codeworld-auth.db johndoe Expired

This will create a new account with user ID johndoe with a randomly generated password. The account will be set to "Expired" which means the user will be prompted to enter a new password at next sign-in time.

Other subcommands are provided for updating and deleting accounts etc. For help:

build/bin/codeworld-auth --help
Create a JWT secret

To use local authentication, you will also need to generate a JWT secret stored in a file named codeworld-auth.txt. This is used to sign JWT tokens passed back and forth between the server and the browser. From the Git repository's root directory, run the following command:

build/bin/codeworld-auth generate-secret -s codeworld-auth.txt

This will generate a new random JWT signing key. The server should not expose this secret to external users.

Swap Space

If you are installing CodeWorld on a virtual server, be aware that the default RAM on these servers is often not sufficient for GHC. CodeWorld needs to compile very large Haskell projects during its installation. The following should be sufficient to resolve any out-of-memory problems you encounter:

$ sudo dd if=/dev/zero of=/swap bs=1024 count=2097152
$ sudo mkswap /swap
$ sudo swapon /swap

This creates a 2 GB swap file to increase available virtual memory. Installation with a swap file may be slow, but it will succeed. (Unless you intend to write very large programs in CodeWorld, it's usually safe to remove the swap file after running the server for the first time.)