Working with the Code and Files
One of the core concepts of platformOS is that you never work offline. You edit the files in your local filesystem with your favourite code editor, but you are constantly connected to your instance so that the platformOS engine can interpret and parse your codebase.
You write code locally, but it is executed remotely.
Proper platformOS directory structure
In order for platformOS to understand and properly interpret your code, it needs to be organized in a specific way.
The simplest method for getting the proper folder structure is to use the
pos-cli init command.
Start with creating an empty folder – named in this example platformos-hello – for your project and then navigating to it from the command line:
mkdir platformos-hello cd platformos-hello
Now, to automatically create the proper directory structure inside that folder use:
The command should return a success message confirming that the directory structure was created.
This means that there are a bunch of new files and folders in your project’s root directory. We’ll explain what they are used for in the next steps of this tutorial, or - if you want to jump in to the technical details - check out the platformOS Codebase section of our documentation.
What you need to know for now is that this command creates an example HTML page with a welcome message.
Authenticate your environment
For pos-cli to know which instance is related to any particular codebase, you need to make a connection between those. Basically, you need to tell the pos-cli that your code needs to be visible under some URL.
Your instance URL is available in the Partner Portal on the Instances list.
To store your instance URL in the configuration, run a
pos-cli env add command with your personal data in the parameters:
pos-cli env add <environment> --email <your email> --url <your instance url>
Run all commands discussed in this tutorial in the project root directory.
You need to give your instance a name in the
<environment> parameter. Since you can connect multiple instances to a single codebase, quite often you'll want to have different environments for development and production.
Let’s assume the first created instance will be for development, thus you can name it
dev. So, the example pos-cli command would look like this:
pos-cli env add dev --email [email protected] —-url https://my-instance.staging.oregon.platform-os.com
After running this command, you’ll get asked for your Partner Portal password to authenticate. Providing the correct password will be confirmed by pos-cli:
Environment <your instance url> as dev has been added successfully.
Upload your code to an instance
When you have an instance, and the pos-cli is configured to connect with it, you can send your code to be available under the instance URL.
This process – called deployment – is a straight-forward operation where you need to use the following command in the root of your project folder:
pos-cli deploy <environment>
So, if you named the alias to your instance
dev, the command would look like this:
pos-cli deploy dev
A progress indicator is shown with the deployment status and once it finishes, a message is displayed:
Deploy succeeded after X seconds
After this, enter the URL of your instance in the browser and it will display the example page that you’ve just deployed.
Testing the deployment process
To test out the whole deployment process, make some changes in the code.
If you’re following this guide, you should be able to find a file named
app/views/pages/index.html.liquid in your codebase. Open it up in your code editor of choice and change any line. For example, locate a line with the welcome message:
Welcome to your Demo instance!
Try changing it into something more personal like:
This is my first platfromOS instance!
Save the file and send the codebase to the instance by running the deploy command in the command line again:
pos-cli deploy dev
After visiting your instance URL or refreshing the previously opened page, you should see the new message there.
Upload code changes automatically when you save the file
On a daily basis, you want the instance to immediately reflect the changes you made in the code with minimum effort on your side.
We call this process syncing and it’s handled by a pos-cli command ran from the root project’s directory:
pos-cli sync <environment>
When executing this command you will learn that it does not end by itself. This is a command that you want to run and leave open while you make code changes.
pos-cli sync is doing is basically observing your codebase, so when you save changes in a file – it automatically uploads it to your instance. It only uploads the file that changed so it’s quick and efficient.
Syncing in action
For this example, try another change in the code, but before you do it, start the sync using the following command:
pos-cli sync dev
A confirmation message saying that the synchronization has been started should appear, so find another place in the code to test how this works. Please find the
Hello world title in
index.html.liquid of the demo page and change it to something else, like
Hello beautiful world.
After the change, just save the file.
In the command line you should see a confirmation message saying that the edited page was synced. Refreshing the page in the browser should confirm that everything worked and the new text content is displayed.
Basic overview of the directory structure
pos-cli init command will create all of the required folders used by platformOS. The very basic directories you need to be aware of are those used to store files, web pages, and handling data.
We have a whole separate article describing each directory's function in detail if you want to jump directly into the technical aspect. The ones mentioned below are enough to start.
- app/assets/images for images
- app/assets/styles for the page CSS
- app/assets/fonts for the font files
Every page that you want to create should be placed in app/views/pages. You can use pure HTML and extend it with Liquid.
The place for schema (the structure of your database written in YAML) is
app/schema. We are going to walk through creating them in the next sections of this tutorial.
GraphQL queries and mutations are used to get the data from the database or save data in it. All of those queries go to