Quickstart Guide

Last edit: Jul 26, 2019
  • Contributors:
  • pavelloz
  • piotrze

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 pos-cli

The pos-cli is a tool that helps you develop and deploy your application.

Note

You will need NPM (Node Package Manager) installed on your computer to install the pos-cli. NPM is distributed with Node.js, which means that by installing Node.js, you automatically get NPM installed on your computer. If you haven't installed Node.js yet, follow our tutorials that walk you through the process on Mac or Windows.

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


npm install -g @platformos/pos-cli

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


sudo npm install -g @platformos/pos-cli

Use the following command to test the pos-cli:


pos-cli -v

If the pos-cli has been installed correctly, running this command displays the version of your pos-cli. If the pos-cli 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 app directory.

You can create the codebase using the pos-cli.


pos-cli init

Note

Make sure you invoke this command where you have permissions to create a directory.

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 (app/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.

Note

Run all commands discussed in this tutorial in the project root directory, i.e. one level above the app directory.

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


pos-cli env add <environment> --email <your email> --url <your marketplace url>

For example:


pos-cli env add staging --email myemail@example.com --url https://example.com

To deploy all changes, run the deploy command:


pos-cli deploy <environment>

For example:


pos-cli 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.