Deploying and Syncing Changes

Last edit: Dec 03, 2019
  • Contributors:
  • pavelloz

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 four-step process:

Step 1: Authenticate environments

Note

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

First, 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 2: Deploy your code

To deploy all of your code, 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 [time]" 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.

Note

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

Your website should be now deployed to your Instance. You can verify that in your browser by going to its URL.

Step 3: Change something in your codebase

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


---
layout_name: 1col
---

<h1>This is home page.</h1>

Open it in a code editor of your choice (we recommend Visual Studio Code because it's free and has many helpful extensions), and add some text. Don't edit the lines between ---:


---
layout_name: 1col
---

<h1>This is home page.</h1>
<p>Hello, World!</p>

Save your changes and deploy your code.


  pos-cli deploy staging

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

Step 4: Sync your changes

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.

Now, remove the text you added in Step 3, and look for the confirmation that the sync command shows.

[16:14:35] Synchronizing changes to: https://example.com/
[16:14:46] [Sync] Synced: views/pages/home.html.liquid

After seeing this confirmation, refresh your site in your browser. The text has been removed.

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.