This tutorial shows how to use Frisk to create and deploy a minimalistic Express.js app and share your work with someone. A very similar method can be used to prototype apps for other frameworks.

Background. It is important that the reader understands the following concepts before continuing.

  • (Frisk) Session: The 2h period a developer can interact with Frisk). Sessions are anonymous, which means you don't have an account to save your work, but note that you can continue and share your work by pressing the share icon. When accessing that link, Frisk creates a new session based on the contents stored in the original session.
  • (Frisk) Virtual Machine (VM): A machine that will be hosted in our servers. You can create as many VMs as necessary for the period of a session. This should be important when working with microsservices.
  • (Docker) Image: A file encapsulating the OS that will be used to run your example. This file is not visible to you (it is stored in the Docker registry). Docker uses the file 'Dockerfile'--this one visible to the user--to create an image. One can find the images available in a virtual machine using the command "$> docker images".
  • (Docker) Container: Conceptually, a container is an image in execution; it is called that way because it isolates a running environment from other containers. One can find all containers available in a virtual machine using the command "$> docker ps -a".
  • (Frisk) Card: A card is a Frisk abstraction to bootstrap a Frisk session. A developer can use a card to start a session with coding artifacts as to speedup prototyping. These artifacts include a Dockerfile and boilerplate code associated with the purpose of the card.

Task 1: Check prerequisites

You will need a modern browser to complete this tutorial. We will explain the pieces of Express.js code covered and the Docker commands discussed along the way, so prior knowledge on these is not needed.

Task 2: Create a session

Select the Express.js card from the home page.

This selection has the following effects:

  • it creates a Frisk session with one virtual machine in it
  • it adds a Dockerfile for Express.js (it does not create image or container)
  • it adds boilerplate code--index.js--for a web service

Task 3: Modify the website

Before continuing, make sure you are in the /root directory by typing pwd from the shell. This is the base directory for making changes in your environment. After that, click the "Editor" button. You can make changes to the files using the file editor that will show up. Alternatively, you can use vim from the shell, if you prefer.

After those checks, modify the file /root/index.js (shown below) to print a different ouput. This file contains Express.js code (a dialect of Node.js) to respond to an HTTP request to the base URL of your app (see string '/' at line 4). Modify the string "Hello world!" however you want. Note that the string is passed to the function send from object res, which denotes the response to an HTTP request.

1: var express = require('express');
2: var app = express();
3: 
4: app.get('/', function(req, res){
5:     res.send("Hello world!"); // <-- here
6: });
7: 
8: app.listen(8080);

Task 4: Create the Docker image

If you don't remember the definition a Docker image, please check the definitions at the beginning of this tutorial.

  1. Display the contents of the Dockerfile.

    $> cat Dockerfile
    FROM node:6.9.5
    RUN mkdir /app && cd /app
    WORKDIR /app
    RUN npm install --save express
    COPY . /app
    EXPOSE 8080
    CMD node index.js
    

    Let's see what each of these commands do.

    • FROM specifies the base image of the new image you're creating (yes, images are layered). For this example, the base image is node:6.9.5, which builds on some Linux distribution.
    • RUN executes the corresponding command in a new layer on top of the current image. The resulting image will be used in the following commands from the Dockerfile.
    • WORKDIR sets the working directory that is used by other Docker commands.
    • COPY copies files from the host (in this case a Frisk VM) into the image. In this example, the COPY command is used to copy the contents of the /root directory (in the host) into the app directory (in the image).
    • EXPOSE sets which port(s) the application uses.
    • CMD specifies what command to run when a container is started from the image.
  2. Use the following command to create the image.

    $> docker image build --tag expressapp:1.0 . 
    • The --tag option specifies a custom name for later reference.
    • The . at the end of the command tells Docker to use the current directory to look for the file Dockerfile

    Execution of this command generates a good amount of output on screen (check if your output matches ours). To sum, this command downloads all dependent images, creates the image expressapp:1.0 based on those pieces, and stores it in the Docker registry. It does not create containers. Check if the image expressapp:1.0 is available in the registry with the command "$> docker images".

Task 5: Spawn the Docker container

  1. Use the following command to start a new container from the image you created.

    $> docker run --publish 8080:8080 --name expressapp expressapp:1.0

    Recall that the CMD command (from the Dockerfile) is responsible for running the Express.js webserver on the container. As this container will be running an Express.JS web server, we need to connect the ports on the VM and the container. The option --publish host_port:container_port does that. It enables traffic to the host (VM) to be forwarded to the container, which is running your service.

  2. At this point, your container should be up and running. You can check that two ways.
    • Copy the ssh command on the top of the page and paste it in on a terminal (any machine) and then type top. You should be able to see referring to the name expressapp. This is the container process.
    • Click on the link 8080 that should have appeared on the top of your session screeen once the container started to run. Your browser should open a new tab for that URL and you should see the message you defined in the file index.js.

Task 6: Share (a copy of) your session

There are two different ways to share work in Frisk. The first alternative provides access to the same session via SSH; the second alternative creates a copy of the session. The first alternative is useful, for example, to ask for help of a colleague to solve a problem in your setup whereas the second alternative is useful to share your work with strangers. Let us focus on the second alternative.

  1. Identify the share-icon button that appears at the top of your screen.
  2. Click on that button, Frisk will show an URL associated with your session.
  3. Copy-and-paste that URL on the browser (it can be a different browser running on a different machine). A click on that link will result in the creation of a new session based on the contents of the original session. The sessions are different! A change in one session is not visible in the other session. If you want to share a running session (without copying it), use the SSH button.
  4. Make a different change on the string message in the index.js file and repeat the commands in this tutorial to confirm that both services are running and they respond with different strings.

Task 7: Close your session(s)

Remove the VM from your session and then close the session. The maximum time of a session is 2h, but it is good practice to save time and space. You can continue your work anytime if you keep the URL for your session.