Hello, World!

Welcome to the first part of our Get Started guide, that will teach you how to set up your development environment, create a simple site, make a small change on the home page, and deploy it. This is to make sure you have everything you need and everything works.

Prerequisite: Register on the Partner Portal

The 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).

To register on the Partner Portal, go to https://partners.platformos.com/accounts/sign_up, fill in the form or use your GitHub or Google account.

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

Step 1: Create an Instance

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 under Create, select Instance, and fill in the form:

Field	Description	Example
Name	The name of your Instance	HelloWorld
Tags	Enter up to 5 tags (optional). You can use tags to group your Instances, for example by project or client.	demo, test
Partner	Select the Partner the Instance will belong to.	HelloWorldPartner
Data Center	Select an endpoint (staging or production).	STAGING

Select the Staging/Unbilled Billing Plan that appears, and 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 2: Install the pos-cli

The pos-cli is a command line interface that helps you deploy configuration files and assets to your platformOS site.

Once you have Node.js installed, start your command-line tool (for example, 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 3: Create your codebase

In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. You can create your codebase organized into the the required directory structure using the pos-cli's init command.

pos-cli init downloads the directory structure in a zip file, and extracts it into the current directory. This means the best way to start is to create a directory for all of your projects and a directory for your project inside of it.

Example directory structure before pos-cli init:

projects
└── hello-world

Change into the hello-world directory and run the pos-cli init command:

pos-cli init

This command creates the required directories, configuration files, and some example files in the directory you specified.

If the directory is empty, the command shows a success message:

$ pos-cli init
[11:35:06] Directory structure successfully created.

If it is not empty (don't forget to think of hidden files), it will require your confirmation by adding the --force flag. Be aware that it will override your files if they conflict.

$ pos-cli init
[11:36:10] Cloning failed. Reason: destination directory is not empty, aborting. Use option force to override.

$ pos-cli init --force
[11:36:43] Directory structure successfully created.

Once you've installed the required directory structure, locate and explore it – this is how your codebase for your platformOS Instances should be organized.

Example directory structure after running pos-cli init:

.
├── LICENSE
├── app
│   ├── assets
│   │   ├── fonts
│   │   │   ├── Gotham-Bold.woff2
│   │   │   ├── Gotham-Book.woff2
│   │   │   ├── Gotham-Light.woff2
│   │   │   └── Gotham-Medium.woff2
│   │   ├── images
│   │   │   ├── logo-black.svg
│   │   │   ├── logo.svg
│   │   │   └── welcome.svg
│   │   ├── scripts
│   │   │   ├── app.js
│   │   │   ├── sw.js
│   │   │   └── vendor.js
│   │   └── styles
│   │       └── app.css
│   ├── authorization_policies
│   │   ├── example_policy.liquid
│   │   └── failing_policy.liquid
│   ├── forms
│   ├── graphql
│   │   └── example.graphql
│   ├── model_schemas
│   ├── api_calls
│   │   └── example.liquid
│   ├── emails
│   │   └── example.liquid
│   ├── smses
│   │       └── example.liquid
│   ├── translations
│   │   ├── en.yml
│   │   └── pl.yml
│   ├── user_profile_types
│   └── views
│       ├── layouts
│       │   ├── 1col.html.liquid
│       │   └── application.html.liquid
│       ├── pages
│       │   ├── admin.html.liquid
│       │   ├── index.html.liquid
│       │   └── unauthorized.html.liquid
│       └── partials
│           └── layout
│               ├── head.liquid
│               └── scripts.liquid
└── modules
    └── example
        ├── private
        │   ├── assets
        │   ├── authorization_policies
        │   ├── forms
        │   ├── graphql
        │   ├── model_schemas
        │   ├── api_calls
        │   ├── emails
        │   ├── smses
        │   ├── translations
        │   ├── user_profile_types
        │   └── views
        │       ├── layouts
        │       ├── pages
        │       └── partials
        └── public
            ├── assets
            ├── authorization_policies
            ├── forms
            ├── graphql
            ├── model_schemas
            ├── api_calls
            ├── emails
            ├── smses
            ├── translations
            ├── user_profile_types
            └── views
                ├── layouts
                ├── pages
                └── partials

To learn more about the required directories and files, visit platformOS Codebase.

pos-cli wizard

pos-cli init’s wizard feature helps you download and install specific example code that the platformOS development team has provided.

Video tutorial:

Usage:

In your terminal, enter:

$ pos-cli init --wizard

This will give you a list of options to choose from:

• empty: Initialize the platformOS directory structure to start from scratch.
• Hello world: Initialize the directory structure and install the application code of the Hello, World! example.
• Todo app: Initialize the directory structure and install the application code of the Building a ToDo List App example.
• Product Marketplace Template: Initialise the directory structure and install the Product Marketplace Template solution.

Select the option you’d like to install and choose the branch you’d like to use from GitHub (the default is the master branch). The code is pulled to your local environment, and you can deploy it to your platformOS Instance.

Step 4: Change something on your homepage

Locate the index.html.liquid file in your codebase.

app/views/pages/index.html.liquid

<div class="flex flex-row flex-wrap min-h-screen justify-start items-start">

  <div class="w-full">
    <div class="bg-ex-darkblue w-full shadow-xl flex items-center h-16">
      <img src="{{ 'images/logo.svg' | asset_url }}" alt="platformOS Logo" width="175" class="ml-4">

      <p class="text-white font-bold -mt-px ml-3 pl-3 border-l border-ex-lightblue">
        Hello world
        <span class="font-light">Your platformOS starter</span>ini
      </p>
    </div>

    <div class="w-full flex justify-center items-start bg-white border-b-2 border-ex-lightgrey">
      <img src="{{ 'images/welcome.svg' | asset_url }}" alt="Hello world!" class="sm:h-96 lg:h-128">
    </div>
  </div>

  <div class="my-10 px-10 md:px-0 w-full">
    <h2 class="text-2xl font-bold text-center">
      Welcome to your Demo instance!
    </h2>

    <div class="max-w-2xl mx-auto mt-10">
      <p class="font-bold text-gray-700">
        No matter what language you speak or frontend frameworks you love, platformOS speaks your language — your unlimited development platform.
      </p>
      <p class="mt-4 font-light">
        This is your Demo Instance: a fully functional example platformOS site that you can use as your own Sandbox. Follow the steps in our Hello, World! tutorial to change something on this site, and check back here to confirm how it has changed. By the time you finish, you’ll be set up to start working on platformOS.
      </p>
    </div>
  </div>

  <div class="bg-ex-lightgrey mt-auto w-full">
    <div class="max-w-2xl flex justify-between items-center mx-auto py-3">
      <img src="{{ 'images/logo-black.svg' | asset_url }}" alt="platformOS Logo" width="135" class="logo-black">

      <ul class="font-light text-sm">
        <li><a href="https://documentation.platformos.com" target="_blank">Documentation</a></li>
      </ul>
    </div>

  </div>
</div>

Open it in a code editor of your choice, locate the "Welcome to your Demo instance!" line and change it to "This is my first platformOS instance!".

<div class="flex flex-row flex-wrap min-h-screen justify-start items-start">

  <div class="w-full">
    <div class="bg-ex-darkblue w-full shadow-xl flex items-center h-16">
      <img src="{{ 'images/logo.svg' | asset_url }}" alt="platformOS Logo" width="175" class="ml-4">

      <p class="text-white font-bold -mt-px ml-3 pl-3 border-l border-ex-lightblue">
        Hello world
        <span class="font-light">Your platformOS starter</span>
      </p>
    </div>

    <div class="w-full flex justify-center items-start bg-white border-b-2 border-ex-lightgrey">
      <img src="{{ 'images/welcome.svg' | asset_url }}" alt="Hello world!" class="sm:h-96 lg:h-128">
    </div>
  </div>

  <div class="my-10 px-10 md:px-0 w-full">
    <h2 class="text-2xl font-bold text-center">
      This is my first platformOS instance!
    </h2>

    <div class="max-w-2xl mx-auto mt-10">
      <p class="font-bold text-gray-700">
        No matter what language you speak or frontend frameworks you love, platformOS speaks your language — your unlimited development platform.
      </p>
      <p class="mt-4 font-light">
        This is your Demo Instance: a fully functional example platformOS site that you can use as your own Sandbox. Follow the steps in our Hello, World! tutorial to change something on this site, and check back here to confirm how it has changed. By the time you finish, you’ll be set up to start working on platformOS.
      </p>
    </div>
  </div>

  <div class="bg-ex-lightgrey mt-auto w-full">
    <div class="max-w-2xl flex justify-between items-center mx-auto py-3">
      <img src="{{ 'images/logo-black.svg' | asset_url }}" alt="platformOS Logo" width="135" class="logo-black">

      <ul class="font-light text-sm">
        <li><a href="https://documentation.platformos.com" target="_blank">Documentation</a></li>
      </ul>
    </div>

  </div>
</div>

Save your changes.

Step 5: Authenticate your environment

Now, you have to specify which Instance will be which environment. For example, you set up one Instance for staging, and another one for production. This information is stored in a config file.

Regardless of what your Instance is called, after you specify it as staging, you can refer to it as staging in all commands where applicable, and you won't have to use the Instance name or the URL of the Instance again.

To add your environment to the config file, run the env add command, and authenticate with your Partner Portal credentials.

pos-cli env add [environment] --url [your Instance URL]

Example:

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

A message "Environment [your Instance URL] as staging has been added successfully." is displayed.

Step 6: Deploy or sync

To be able to check your changes on your site, you have to deploy those changes to your Instance.

Deploying

To deploy all changes, run the deploy command:

pos-cli deploy [environment]

Example:

pos-cli deploy staging

A progress indicator shows that the deployment is in progress, and once it finishes, a "Deploy succeeded after " is displayed.

We recommend to first deploy to staging, test, and only then trigger a deployment to production. In practice, deploy creates a zip file that contains all your files, and sends it to the API. It is then processed in the background. We store each zip file, so that you can roll back in case something goes wrong.

Syncing

To immediately push changes in your codebase to the environment, run the sync command:

pos-cli sync [environment]

Example:

pos-cli sync staging

Using the sync command feels like working on localhost. It is recommended to use sync only for staging environments, as pushing changes immediately to production can be dangerous. Please note, that unlike deploy, this command will not delete resources when you delete the file.

After you have deployed your Instance, refresh your site in your browser. The home page has changed to include the text you added.

Read Effective Development Using pos-cli for more information.

Congratulations, you have finished our Hello, World! guide: You have set up your environment and learned how to change something on your site and deploy it.