CoCalc Blog

Running Your own Free CoCalc Docker Server on Google Cloud Platform

William Stein • • cocalc


CoCalc is a web application that lets you collaboratively use a large amount of free open source math and data related open source software. You can create collaborative Jupyter notebooks, edit LaTeX documents, use Terminals, use graphical Linux applications, create chatrooms, and much more. There’s extensive support for SageMath, Octave (a MATLAB clone), and R. See the docs.

Cocalc-docker is a completely free and open source self contained version of CoCalc, which you can run on your own computer or cloud server. This post is about how to freely play around with running CoCalc-docker on Google Cloud Platform.

If you scroll down and see all the cool things CoCalc can do, but don’t want to bother running your own server, make an account at CoCalc and use our hosted service, which has filesystem snapshots, a vast amount of preinstalled software (much more than cocalc-docker), and support.

Sign up for Google Cloud Platform

Click above to learn about Google Cloud Platform's free trial

Create a Container Instance

Where to run it?

Choose a location near you:

Choose where to run the container close to you, for optimal speed!

Select to run a container directly (and configure your machine type)

Click the checkbox next to “Deploy a container image to this VM instance.”, then put sagemathinc/cocalc in the blank below “Container image”. Also check the boxes next to buffer stdin and allocate a tty.

You can also change the machine type, though the default will work.

Container Image and Machine type

Increase Base Image Size to at least 20GB!
CRITICAL: increase the base image size to at least 20GB! The default of 10GB will fail.

Allow the container to provide an HTTP/HTTPS web server

Enable https and http access

Make the instance pre-emptible (optional)

If you are just playing around to test this out, open “Management, security, disks, networking, sole tenancy” and scroll down and set “Preemptibility” to On. This will make things way cheaper (using less of your free trial credits). This is especially useful if you wan to do a relatively quick but very CPU intensive parallel computation.

Here’s how our cost estimate comes out so far, with preemptible on. It would be about four times as expensive without preemptible on.

Pretty cheap...

Of course the drawback of preemptible is that the machine will be killed within 24 hours. That’s fine for testing things out though.

Click Create at the bottom to start creating your VM

You'll see this line in your list of VM's when the instance is being created

Watch the Serial Port

Once the VM is created, click to open it, then click “Serial port 1 (console)” (or “Connect to serial console”), to watch the log as the machine boots up.

Watch the Serial Port

It takes at least 10 minutes to pull and decompress the sagemathinc/cocalc Docker image. If this fails, you probably forgot to increase the size of the boot disk from 10GB to 20GB (or more), in which case you should delete everything and start over.

Wait at least 10 minutes until you see the above

Determine the IP address

Once your machine is running and the sagemathinc/cocalc image has been pulled and decompressed, find the external ip address of your machine, and open it in a new browser tab. In my case, I open

Do NOT choose the address that starts 10., since that is internal.

Copy your IP address

If this fails, you probably forgot to check the box next to “Allow HTTPS traffic”.

Security warning

Since the SSL cert in the Docker image is self-signed, you’ll get a warning. Click through it by clicking “ADVANCED”.


Click Proceed...

Create a new account on your personal CoCalc server

Click to create an account...

Create an account

WARNING: Anybody who knows the IP address can make an account in the same way. There’s no secret token, and currenly no way to configure one with GCP Container Image. See this issue.


Click the network icon in the upper right:

Your ping time should be small

Make a test project

Make a project

Open your project

Let’s take our project for a spin

Click “+New” (or click the big “Create or Upload” button) to show the new file page:

Start using it by creating a file

Make whatever files you want and play around with them. I’ll make a few below, just for fun, to give you a sense of what is possible.

The Octave Graphical Interface

Octave is a MATLAB clone, and you can run the graphical UI of Octave by clicking “X11 Desktop”, then typing octave, and clicking the tab on the right when it appears. I copied some code to draw a 3d plot:

Using the Octave Graphical Interface

Graphical Linux applications should be pretty fast, since the server is dedicated to you and should be very close to you.

In the image above, I split the X11 frame to show the graphics on one side and the Octave UI on the other.

A Jupyter Notebook

Next, let’s create a Jupyter notebook:

In the +New page, click on "Jupyter notebook".

Once the notebook appears, I set the kernel to Octave, and pasted the same code in:

Drawing a Sombrero using Jupyter and Octave

A Sage Worksheet

Next, let’s make a SageMath worksheet; of course CoCalc-docker comes with the latest version of Sage.

Click the Sage worksheet button

Let’s draw an interactive 3d plot using Sage.

Choose a plot from the drop down menu

You should be able to rotate 3d plots around with your mouse:

I chose a 3D polytope

You can find thousands of additional plotting examples in the Sage reference manual.

Use LaTeX

Next, let’s create a LaTeX document.

In +New, click LaTeX

A new LaTeX editor will appear. Edit source on the left, see the preview (on save) on the right. Double click the preview to go to the corresponding point in the source, etc.

Edit a LaTeX document


Click Files at the top and you’ll see that we’ve made a lot of files:

Files in our Project

Full Emacs

For fun, let’s click on the tab for your X11 desktop (the file ending in .x11), then type

emacs *.tex &

to open that same LaTeX file in Emacs. Then click the Emacs tab on the right.

Open our LaTeX file in classical Emacs in the X11 Desktop

You can hit control+c twice in Emacs to build the LaTeX file from there, and have full AUCTeX support.

Microsoft Visual Studio Code

Visual Studio Code is also included with cocalc-docker. I tried using the LEAN proof assistant in it and it works great.

In your X11 Desktop (file ending .x11 terminal), type code a.lean & and VS Code pops up.

Using Microsoft Visual Studio Code's LEAN proof assistant mode

When you edit the file, it’ll offer to search the marketplace for a plugin to support LEAN. It’ll install it with a click, and then you have LEAN fully working. Note that the LEAN server itself is already preinstalled in CoCalc-docker, and you can also just open a.lean directly from the Files listing in CoCalc to use CoCalc’s own LEAN editor (or you could install one in Emacs).

Draw some Doodles

CoCalc-docker also includes Inkscape and Libreoffice:

Doodle in Inkscape and Libreoffice draw

Learn how to write Python3 Games

You can even use pygame to write and play Python3 Games:

Play a Game

NOTE: sound is currently not supported.


Thanks for giving Cocalc-Docker a spin. I hope you find the wide range of collaborative web-based functionality useful to supporting your teaching and research. Please let me (William Stein) know what you think in the comments below, or by emailing [email protected].