Deploying and Syncing Changes

This guide will help you deploy and sync changes you make in your codebase to your Instance. To demonstrate the process, you'll make a small change on your home page, and deploy it to your Instance.

Requirements

In order to deploy and sync changes to your Instance, you will need an Instance set up on the Partner Portal, and the pos-cli installed on your computer. You will also need to have the codebase for your Instance organized into the required directory structure.

Steps

Deploying and syncing changes is a three-step process:

Step 1: Change something in your codebase

Locate the home.liquid file in your codebase (app/views/pages/home.liquid).


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

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.

Step 2: Authenticate environments

Note

Make sure you remember your Partner Portal account email and password — you will need them to authenticate your environments.

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.

Note

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


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

Tip

You can copy this command pre-filled with your email and Instance URL from your Instance page on the Partner Portal.

Example:


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

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

Step 3: Deploy or sync changes

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

Note


This step describes two different methods. If this is your first go, we recommend to follow the process described in the "Deploying" section.

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.

Tip


Learn more about our recommendations for version control and deployment on platformOS in the Development Workflow topic.

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.

Next steps

Congratulations! You can deploy and sync your codebase to your Instance. Now, you can delve into learning more about development on platformOS.

Questions?

We are always happy to help with any questions you may have.