quick-start

Quick Start

Project Setup

1. Clone and install dependencies ⬇️

🔧 Tooling: The project uses node.js and yarn "classic". You must have both installed.

🚀 Execute the following commands:

git clone https://github.com/nearform/orion.git
cd orion
yarn

🔧 Tooling: The repo uses lerna and yarn workspaces to work as monorepo. The individual packages are located in the packages sub directory.

2. IDE setup ⚙️

Orion uses the xo linter 🐛. It is very strict and is intended to eliminate all style debates.

Developers are assumed to be using VSCode. Use other IDEs at your own risk.

🚀 Install the XO extension for VSCode

ℹ️ Info: There are xo extensions for other IDEs. Use them at your own risk.

🚀 For the best VSCode experience, enable the xo formatter and the format on save options:

{
  "editor.formatOnSave": true,
  "xo.enable": true,
  "xo.format.enable": true
}

💡 Pro tip: The linter only works in VSCode when opening the project from the root of the the monorepo. Opening individual packages will lead to headaches 🤕💊.

3. Configure ⚙️

Configuration happens through environment variables.

🔧 Tooling: Environment variables are loaded with env-cmd or dotenv depending on the pacakage.

Required environment variables for each package are documented in the .env.sample files inside the associated packages.

The following packages distinguish between .env.development and .env.production when running in development mode or building for production:

• gatsby-plugin-orion-edit
• gatsby-plugin-orion-view

The package hasura does not make a distinction and has a single .env file.

⚠️ Warning: by setting the .env files as in .env.sample you will be running the apps to run in Bypass authentication mode. This mode is ment to be used in development environment. Contact us in the case you need to run Orion in production environment.

Run

1. Launch the sites locally 💻

🚀 Run the command(s) for the site(s) you want develop:

• Run hasura and postgres in local docker container and run view and edit websites. This is the right script to have everything running in you local environment.

run start:dev

• Run hasura and postgres in local docker container (no clients running)

run start:db

• Stop hasura docker container, drop all docker volumes and drop postgres db

run stop:db

• Start view client (no db connection unless you set up your own)

yarn start:view

• Start edit client (no db connection unless you set up your own)

yarn start:edit

⚠️ Warning: In any case you need to set up the right environment variables. Please refer to Configure section

2. Debug the sites in your browser 🚫🐛

Once Gatsby successfully builds and starts the development server(s) the sites can be debugged in your browser.

🚀 Navigate to http://localhost:8000 (view), or http://localhost:8001 (edit) as required.

3. Development user 👨👩 (Bypass authentication mode)

As you are running Orion in Bypass authentication mode you need to set up your develoment user credentials as environment variables. Please refer to .env.development.sample files to get more info

4. Storybook 📖

As appropriate, individual components should be demo'able in storybook.

🚀 Run story book locally:

yarn storybook

🚀 View the staging version of storybook at https://orion-storybook.nearform.com

Contribute 📝

1. Prepare 👨‍🏭

🚀 Pick a story to work on from the clubhouse project.

🚀 Work on a new branch, using the name suggested by clubhouse by clicking on the github helpers button on your story.

Clubhouse will suggest the convention {username}/ch{story number}/{story-summary}. For example codyzu/ch81/poc-automatic-versioning-in-ci.

2. Commit ⬆️

🚀 Run yarn commit in the console

👆 This is the easy way to commit and will guide you through the commit conventions!

Staged changes and commit messages are linted. You have been warned. Seemingly incoherent linting problems during commits could be due to missing changes in the git staging area.

💡 Pro Tip: If your commit fails (linting or other problems), it can retried with yarn commit --retry (see commitizen's docs for details).

💡 Pro Tip: When prompted for "Issues this commit closes" using the format [ch1234]. This will link your commit to your story.

⚠️ Warning: When prompted for "BREAKING CHANGE", leave the prompt blank and press enter (unless you have a breaking change to report). Entering n or none will result in a new major version and a corresponding note in the changelog!

🚑 In case of emergency (or when rebasing), you can disable commit linting by deactivating git hooks with either of the following:

• yarn commit --no-verify
• git commit --no-verify ...
• HUSKY_SKIP_HOOKS=1 git ...

2. Github PR and Review 🔍

🚀 Create a pull request in Github and ask someone to review it.

3. Merge into master 🔀

🚀 Ensure your branch is built successfully by Circle CI

🚀 Once approved, you as the author of the PR should merge it.

⚠️ Warning: Every developer is responsible that their merge into master builds successfully in Circle CI.

4. Deploy to Staging 🏭

Deploying master into staging can be done by anyone.

🚀 Create a PR merging from master into staging and merge it to trigger a staging deployment

⚠️ Warning: Ensure your deployment succeeds by monitoring Circle CI.