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.
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.
Deploying and syncing changes is a four-step process:
Step 1: Authenticate environments
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.
Run all commands discussed in this tutorial in the project root directory, i.e. one level above the
pos-cli env add [environment] --email [your email] --url [your Instance URL]
You can copy this command pre-filled with your email and Instance URL from your Instance page on the Partner Portal.
pos-cli env add staging --email firstname.lastname@example.org --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
pos-cli deploy [environment]
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.
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
home.html.liquid file in your codebase (
--- 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
pos-cli sync [environment]
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.
Congratulations! You can deploy and sync your codebase to your Instance. Now, you can delve into learning more about development on platformOS.