Quickstart Guide

The easiest way to try out Plane is to use Docker Compose. These instructions are for a Linux or Mac environment with Docker installed.

Quickstart Steps

1. Clone Plane’s git repo (opens in a new tab)

git clone https://github.com/jamsocket/plane.git
cd plane

2. Start Plane

docker compose -f docker/docker-compose.yml up

This will run:

• An instance of Postgres
• A Plane controller
• A Plane “drone”
• A Plane proxy

See the architecture overview for background on each Plane component.

3. Connect to a backend

docker/cli.sh \
    connect \
    --cluster 'localhost:9090' \
    --key 'my-first-backend' \
    --image 'ghcr.io/jamsocket/demo-image-drop-four'

You can think of Plane as a big key-value store that associates “keys” (arbitrary strings) with running processes (session backends).

When you issue a “connect” request, Plane will return a URL that routes to the process associated with the key you provide. If no process is running, Plane will start one (provided that you supply an image name in the connect request).

Here’s a breakdown of the command above:

• docker/cli.sh is a shell script that runs the Plane CLI in a Docker container, pre-configuring it to point to a Plane instance started in the Docker Compose file.
• connect is the Plane CLI subcommand for issuing a “connect request”, which will return a URL that routes to a backend process.
• --cluster 'localhost:9090' tells the CLI to start the backend on the localhost:9090 cluster. Since the cluster name includes a port (:9090), Plane will treat it as a “development” cluster and not enable HTTPS on it. See clusters for more details.
• --key 'my-first-backend' tells the CLI to associate the backend with the key my-first-backend. The first time we run this command, no backend with the key my-first-backend will exist, so Plane will start a new backend process. If we subsequently run this command again while that backend process is still running, Plane will return a URL that routes to that backend process.
• --image '...' tells the CLI that if it needs to start a new backend process, it should use the given Docker image. In this case, the image serves a simple turn-based multiplayer game.

When you run the command above, you should see output like this:

Created backend: ba-xt8nmtlgti18qx
URL: http://localhost:9090/tYVHfS4PKgufdhwGCnn6LLfAaCo_iAHitbw4Bg8ETjA/
Status URL: http://0.0.0.0:8080/pub/c/localhost:9090/b/ba-xt8nmtlgti18qx/status

The first line tells you that Plane has created a backend with the key ba-xt8nmtlgti18qx. The second line tells you a URL that routes to that backend. The third line tells you a URL that you can use to check the status of the backend as JSON.

Below that output, it will show a running list of states and the time they were entered. The first time you run a particular image, it may spend some time in the loading state, because it will download the container image if it does not have it cached.

Once the image is in the ready state, you can open the URL provided in your browser to open the game.

Docker Compose Configuration

The Docker Compose file defines four services:

Note that the name of the cluster (localhost:9090) refers to the port of the proxy, not the controller. This is because the name of the cluster refers to the address that end-user clients will use to access the backends, and clients access backends through the cluster. See the documentation on clusters for more information.