Openinfra.dev is built using a starter template from Netlify CMS, which is running Gatsby. In order to run a local environment, you will need to download several libraries, and will also need the public repo for the website.
The public repository is hosted on GitHub, and can be found here: https://github.com/OpenStackweb/osf-website
Here are the prerequisites you will need to download in order to run a local version of this site:
- Node.js version 8.2.0 or higher
- Important - the site runs Node version 12.22.0. Running a node verison (using npx to control your node/npm version) close to this will ensure the local site is stable
- Python 2.7
- Important - running Python 3 as your default for the “python” command is not recommended. On a Mac, this shouldn’t be an issue, as Mac OS runs Python 2 by default. However, on Windows you may need to edit your path to ensure Python 2 is the default command. Instructions for doing this will be found below
- Install the Gatsby CLI. The installation guide is here
- Install the Netlify CLI
- Install yarn
On Windows, you may run into issues with Python 3 as your default command. If you are getting a failure to compile error, check your path by using the following steps:
- Using File Explorer, go to This PC, and right click to select Properties
- Click on Advanced System Settings, and then select System Properties
- Click on the Advanced tab, and then find the Environment Variables… button
- You should see a User Variables list, and then a System Variables list - we want to go into the System Variables list and find the variable that says path
- Click Edit, and find your download of Python 2.7 - move that to the top of your path, then select OK
The site follows the JAMstack architecture by using Git as a single source of truth, and Netlify for continuous deployment, and CDN distribution.
Once you have the prerequisites needed to run the site, you will need to run the following commands:
git clonethe GitHub repository into the folder of your choice on your local machine. The repo can be found here: https://github.com/OpenStackweb/osf-websitecdinto the repository once it has been cloned onto your machine- Run the
yarncommand to install dependencies
These steps are repeated below if you want to copy and paste into your terminal (you will need to adjust the git clone command to match the actual repo on GitHub):
$ git clone https://github.com/OpenStackweb/osf-website.git
$ cd [REPO_NAME]
$ yarn
Important - the website will also require a .env file that is not included in the public repository. Reach out to your administrator in order to get this file. The .env file will need to be placed in the root of your project directory.
Once you have the dependencies installed and the .env file at the root of your project directory, you are ready to run the website.
You can use several commands in order to run the site. The first command is yarn develop, and this will compile and format the code, and will run the site locally without the Netlify CMS portion:
$ yarn develop
If you need to run the site locally with the Netlify CMS attached, you can use the netlify dev command, or ntl dev shorthand:
$ netlify dev # or ntl dev
You can also build a complete copy of the site on a separate Netlify environment, and pull that code into your local environment. To do this, click the button below to copy the GitHub repository into your own Netlify account:
After clicking that button, you’ll authenticate with GitHub and choose a repository name. Netlify will then automatically create a repository in your GitHub account with a copy of the files from this repository. Next, it will build and deploy the new site on Netlify, bringing you to the site dashboard when the build is complete. You will then need to set up Netlify’s Identity service to authorize users to log in to the CMS.
You will need to pull down a local copy of the Github repository Netlify created for you, with the name you specified in the previous step:
$ git clone https://github.com/[GITHUB_USERNAME]/[REPO_NAME].git
$ cd [REPO_NAME]
$ yarn
You can then run this local environment using either the yarn develop command or the netlify dev command.
$ yarn develop
OR
$ netlify dev # or ntl dev
$ netlify dev # or ntl dev
This uses Netlify Dev CLI feature to serve any functions you have in the lambda folder, includes the gatsby dev environment. For more info check the Netlify Dev Docs.
$ yarn build
Build the static files into the public folder, and turns lambda functions into a deployable form.
$ yarn clean
Runs gatsby clean command. For more info about this command, check the Gatsby Commands Documentation.
$ yarn develop
Runs the clean script and starts the gatsby develop server using the command gatsby develop. We recomend using this command when you don't need Netlify specific features.
$ yarn start
Functions the same as the develop command, this runs the clean script and starts the gatsby develop server using the command gatsby develop.
$ yarn format
Formats code and docs according to our style guidelines using prettier.
If you have changes you’d like to make to the production website, check out a separate branch on your local, make the changes, and check to ensure functionality on your local machine.
Once you are ready to merge your changes into production, push up your local branch, and create a pull request on GitHub. This will run your new code in a preview environment, and the system will also test your code to make sure it will run on the production environment.
After the new branch has been successfully tested, a preview link with the updates will become available. You can use this link to review the pull request to make sure your changes are running correctly.
After reviewing your own changes, you will need to either use GitHub's review feature or the OpenInfra Foundation's Slack channel to request a review of your changes and to ensure everything still functions as intended.
Once this review stage has been completed, your changes can be merged into production.