Quickstart Guide

Last edit: 

Contributors: 

Welcome to the platformOS Quickstart Guide!

This guide will take you from setting up your development environment to deploying your first platformOS site. After you get access to the Partner Portal in step 1, following and finishing the steps in this guide should take less than half an hour.

Let's get started!

Step 1: Get access to the Partner Portal

Our Partner Portal is an online interface, where you can create, manage and configure your sites (called Instances), and create and manage the permissions of other users (called Partners).

Send us an email, or call us to register an account for you on the Partner Portal.

You can also get access to the Partner Portal if a registered Partner creates an account for you.

Once registered, you will get an email invitation. Click on the Accept invitation link to activate your account.

Clicking on the link redirects you to a page where you can set your password. Enter a password in the Password field, then repeat your password in the Password confirmation field.

Click on the Set my password button. If the two passwords you entered match, you are logged in to the Partner Portal.

Step 2: Set up a site on our platform

To be able to deploy your site, you have to create an Instance on the Partner Portal. Instances have a URL, and they represent different development environments, like staging or production. We recommend creating a staging environment for going through the steps in this tutorial.

On the Partner Portal, in the menu on the left, click on Create, select Instance, and fill in the form:

  • Name: Enter a name for your Instance.
  • Partner: Select a Partner the Instance will belong to.
  • Endpoint: Select an endpoint (staging or production). Endpoints for staging sites have a "staging-" prefix.
  • Billing Plan: Select a Billing Plan for the Instance.

Click on the Create button. We create the Instance, and once it's done (in a couple of minutes), send you an email with a link to your Instance and other useful information.

Step 3: Install the Marketplace Kit

The Marketplace Kit is a tool that helps you develop and deploy your application.

Start your command-line tool (e.g. Terminal on a Mac, or Git Bash on Windows), and enter:


npm install -g @platform-os/marketplace-kit

If your Node.js is installed for all users you might need to use sudo to install npm packages globally:


sudo npm install -g @platform-os/marketplace-kit

You can follow the installation process in your command-line (something similar to this will be displayed during installation):


/usr/local/bin/marketplace-kit -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit
/usr/local/bin/marketplace-kit-env -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-env
/usr/local/bin/marketplace-kit-archive -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-archive
/usr/local/bin/marketplace-kit-env-add -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-env-add
/usr/local/bin/marketplace-kit-deploy -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-deploy
/usr/local/bin/marketplace-kit-env-list -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-env-list
/usr/local/bin/marketplace-kit-push -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-push
/usr/local/bin/marketplace-kit-sync -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-sync
/usr/local/bin/marketplace-kit-watch -> /usr/local/lib/node_modules/@platform-os/marketplace-kit/marketplace-kit-watch
+ @platform-os/marketplace-kit@1.0.5
added 88 packages in 6.719s

Use the following command to test the Marketplace Kit:


marketplace-kit -V

If the Marketplace Kit has been installed correctly, running this command displays the version of your Marketplace Kit. If the Marketplace Kit hasn't been installed, running this command gives a command not found error.

Step 4: Create the Codebase

In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. The root directory of your project should contain the marketplace_builder directory.

You can create the codebase using the marketplace-kit.


marketplace-kit init

Once you've installed the required directory structure, locate and explore it – this is how your codebase for your platformOS Instances should be organized. To learn more about the required directories and files, see platformOS Codebase.

Step 5: Change something and deploy your change

In this final step, you'll make a small change on your home page, and deploy it.

Locate the home.liquid file in your codebase (marketplace_builder/views/pages/home.liquid). Open it in a code editor of your choice, and add some text. Don't edit the lines between ---:


---
slug: /
layout_name: 1col
---
{%- assign name = 'Home' -%}
{%- content_for 'pagetitle' -%}{{ name }}{%- endcontent_for -%}
<h1>{{ name }}</h1>
Hello, World!
 

Save your changes.

Now, you have to authenticate your environment to be able to deploy your changes.

To add your environment to the .marketplace-kit config file, run the env add command, and authenticate with your credentials:


marketplace-kit env add <environment> --email <your email> --url <your marketplace url>

For example:


marketplace-kit env add staging --email myemail@example.com --url https://example.com

To deploy all changes, run the deploy command:


marketplace-kit deploy <environment>

For example:


marketplace-kit deploy staging

Now, refresh your Instance in your browser, and you can see the change you made.

Congratulations! You have set up all the basic components you need for working with platformOS and successfully deployed your first site.

Next steps

Learn more about platformOS, and delve into developing your site by following our step-by step tutorials — it's a good idea to start with Pages.

Questions?

We are always happy to help with any questions you may have. Check out our Help page, or contact us.