Golden Platform starter

This repository is a helper repository to start working on the standardized Golden Platform of platformOS.

Prerequisites

We are using a collection of tools that you should understand at least the basics of to work with the Golden Platform.

1. A basic understanding of the command line
2. A basic understanding of GIT
3. GIT Submodules for using various modules developed for the Golden Platform
4. The very basics of npm for developement tools
5. Understanding of platformOS
6. The Liquid Markup for building templates and provide dynamic configuration

How to start development using the Golden Platform

Get the codebase

If you are using HTTPS to authenticate with GitHub:

1. Clone the repository with

   git clone https://github.com/Platform-OS/pos-golden-starter.git
   

2. Open .gitmodules from the root directory of the cloned repository and edit all of the URLs from the default SHH to HTTPS as in the example: git@github.com:Platform-OS/pos-module-core.git to https://github.com/Platform-OS/pos-module-core.git
3. Save the file
4. Run the following command from the root of the repository folder to install all of the submodules:

   git submodule update --init --recursive
   

If you are using SSH to authenticate with GitHub:

1. Clone the repository using the following command (this will install the default modules as well):

   git clone --recurse-submodules git@github.com:Platform-OS/pos-golden-starter.git
   

Install the platformOS Command Line Interface

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

Assuming you already have npm installed on your system run:

npm install -g @platformos/pos-cli

Create your platformOS instance

Assuming you already have an account in the platformOS Partner Portal and are logged in:

1. Go to https://partners.platformos.com/instances/new
2. Follow the instructions on screen
3. From the root repository directory add the instance to pos-cli config using

   pos-cli env add dev --email <YOUR_EMAIL> --url <YOUR_INSTANCE_URL>
   

This will add the instance with a dev alias as the developement tools assume this will be the name of your default developement instance. You can change it to whatever name you want but some of the npm commands assume that dev is the default.

Deploy the code

1. In the command line go to the root of the cloned repository
2. Run

   pos-cli deploy dev
   

3. Open your instance URL in the browser to verify if everything went successfully. You should see a waving hand emoji (👋).

Install and manage modules

Golden Platform modules are self-contained building blocks that you can use to create complex and customized webpages and applications.

Modules are managed using GIT Submodules. To install a module, you need to run the following command in the .\modules\ subfolder:

git submodule add <module_remote_url> <destination_folder>

Please keep in mind that the <destination_folder> should be a module name without the pos-module- prefix that it is by default. This additional step is required in the developement stage, but will be replaced by a separate pos-cli command in the near future.

As an example, install the Components Library Module from the root of the main repository:

cd ./modules/
git submodule add https://github.com/Platform-OS/pos-module-components.git ./components/

To deploy the newly added module, get back to the root directory and run the corresponding pos-cli command:

cd ..
pos-cli deploy dev

For detailed information on how to use each module, please refer to its Readme.

List of currently available modules:

1. PlatformOS Core
2. Components Library
3. Theme Manager
4. User
5. Permission
6. Admin

To update a module to the newest version use:

git submodule update --remote --merge

Start developing

[TBD]

To learn about modules integration please refer to the hook system.

To create your own module please refer to the Module Template repository.

To create your own theme please refer to the Theme Module Starter repository.