Create a project

June 3, 2016

A project is a representation of an application/software that you have build on Spacedecode. Projects contain source code, files and dependencies (vessel) that run it.

Create your first project

Before we can begin, ensure that you have a Spacedecode account, if you don’t have one yet you may create it here. Also ensure you have downloaded the runtime application. After installing the runtime engine, you will get a graphical desktop interface and a commandline interface for managing your projects.

Let’s begin!

Using the command-line, run the command below (replace “<project_name>” with the name of the project).

$ spaced project create <project_name>

Note: Projects can also be created using the UI.

Once created, the project will be available in the workspace with the .proj file extension.

Note: Spacedecode creates a directory SpaceD on the user home directory. We refer to this folder as the workspace and it is where everything you create is stored.


To create a project named helloworld, run the following command:

$ spaced project create helloworld

If it all goes well, the project will now be available in your workspace. For example:

Project in the workspace

Viewed from the UI, your new project appears like this:

Project as seen on the GUI

Read more about projects here.

Adding a vessel

Vessels are computing units you can add to your project to run services. Think of a vessel as a version-controllable light-weight virtual machine (or linux container). You can use vessels to run just about anything from web servers to database servers. Vessels allow you to break your project down into multiple services for scalability. Read more about vessels here.

Vessels are created inside a project and they are created from recipes. Recipes are previous instances of a running vessel that were captured to re-use. Learn more about recipes here.

To create your first vessel you need the following:

Using the commandline interface

  • You need to the tag of the recipe you want to create the vessel from. See available recipes here. Vessel tags are in this form: username/name. For example, you might find one like this spacedecode/nginx.

  • You also need to know the tag of the project to which you want to add the vessel. The project tag has the same form as the recipe tag.

Using the graphical interface

  • You only need to know the software you want to run as a base. For example creating a vessel running wordpress, you just need to use wordpress as a search query on the dropdown shown below.

  • You also need to select the correct project.

Create the vessel now

Using the commandline, run the following command:

$ spaced vessel create <vessel_name> -p <project_tag> -r <recipe_tag>

NB: Replace the tags with actual values.

If I want to add a vessel to the project we created above, run the following command:

$ spaced vessel create web -p sithembisok/helloworld -r sithembisok/nginx

NB: Note that my username is sithembisok. You will have to replace sithembisok with your username.

This is how you create a vessel from the graphical interface:

Selecting a recipe

Important! The recipe autocomplete searches for recipes both in the local repository and the central repository at This works best if you have an internet connection.

This is how the vessel looks like on the workspace:

Vessel in the workspace

Important! All vessels are represented as folders with a .vsl file extension.

Running the project

Since you now have at least one vessel inside the project, you can now run it. Here are our expectations for this part of the exercise:

  • Since we created a vessel web.vsl from the sithembisok/nginx recipe, we expect to have Nginx running when we fire up the project. We will know it’s running by visiting http://localhost or on the web browser and we should see something.

  • Since we only have one vessel inside the project, starting it will change the entire project’s status to RUNNING. See how we check that below.

Okay, let’s go for it. To run the project, run the following command:

$ spaced project start sithembisok/helloworld

Sample response:

web starting...
Vessel started successfully
web started
Project started successfully

To see if the project started successfully, enter http://localhost on your web browser as per our expectations above and you should see a page similar to this (differs depending on the recipe used).

Nginx default page

You can also run the project from the graphical interface. Locate the power button when you select the project. Now that the project is already running, the power button and all status indicators for the project are green in color.

Running project in the GUI

Please note: You can also see which projects are running by running this command:

$ spaced project list

You will see something like this:

Project list from CLI

See also

comments powered by Disqus