Skip to main content

Local Development Environment Setup

note

Environment setup instructions are written for developers using the latest public release of macOS. Windows/Linux developers may find that additional/alternate steps are needed to install dependencies and set up their local environment. Official Windows/Linux instructions coming soon.

Install Dependencies​

When working with Organic CMS for the first time, Organic strongly recommends installing all listed dependencies, regardless of your role as a frontend, backend, or fullstack developer.

Organic encourages all developers to install and use Homebrew to efficiently manage packages/dependencies locally. A command is provided below for installing all dependencies at once using Homebrew.

Homebrew Bulk Install Command​

brew install \
awscli \
python3 \
node \
yarn \
docker \
nss mkcert

Homebrew Individual Install Commands​

If you run into any errors installing dependencies in bulk, individual formulae can be installed with brew install <FORMULA_NAME> commands.

brew install awscli
brew install python3
brew install node
brew install yarn
brew install docker
brew install nss mkcert

Configure Dependencies​

Configure the AWS CLI​

Click here for detailed instructions for configuring the AWS CLI.

Summary:

  1. Request AWS access from Organic Support.
  2. Create an AWS Access Key.
  3. Configure an AWS CLI Profile using aws configure.
NameValue
AWS Access Key IDSee Detailed Instructions
AWS Secret Access Key IDSee Detailed Instructions
Default Region Nameus-west-2
Default Output Formatjson

Configure SSH for GitHub​

Click here for instructions on configuring SSH for GitHub.

This is required for interacting with GitHub from the command line. It allows you to access and write data in your repositories.

Set Up a Site for Local Development​

1. Clone your site's GitHub repository​

This step creates a local copy of your site's repository.

git clone git@github.com:orgnc/<REPOSITORY_NAME>.git <LOCAL_PROJECT_FOLDER>
cd <LOCAL_PROJECT_FOLDER>

2. Install the Organic Dev tool​

This step updates to the latest version of pip3, creates a virtual Python environment, and installs the latest version of the Organic Dev tool.

pip3 install --upgrade pip
python3 -m venv .venv && source .venv/bin/activate
aws codeartifact login --tool pip --domain organic --repository organic
pip install organic-dev-core

3. Run environment setup command​

This step spins up base Docker containers, generates local SSL certificates, updates localhost files, and creates git-commit hooks.

organic-cli setup
info

The organic-dev command is now organic-cli. If you configured your environment using the old command, you'll need to update Organic Dev.

4. Prepare environment variables​

In this step, we'll define environment variables for our project.

Project environment variables​

  1. Navigate to your project folder and copy the .env.example file. Name it .env.
    • This file may not be visible in Finder. To show hidden files, press Command + Shift + ..
  2. Open the .env file in your IDE or text editor.
  3. MacOS Users: Uncomment DOCKER_HOST=host.docker.internal.
  4. Replace your_github_token_here with a personal GitHub access token (classic).
  5. Replace yoast-passwd with a valid Yoast SEO Premium token.
    • This token is not required unless you are working on Yoast-related features.
    • Contact Organic Support for a token if your organization does not maintain a Yoast SEO Premium account.
  6. Save & close the file.

Backend environment variables​

  1. Navigate to the backend/src folder and copy the .env.example file. Name it .env.
  2. Replace <aws_access_key_id> with a personal AWS Access Key ID. This can be the same AWS Access Key ID created for the AWS CLI above.
  3. Replace <aws_secret_access_key> with a personal AWS Secret Access Key. This can be the same AWS Secret Access Key created for the AWS CLI above.
  4. Save & close the file.

Frontend environment variables​

Navigate to the frontend folder and copy the .env.local.example file. Name it .env.local.

Enable previews​

To enable CMS previews:

  1. Retrieve token from AWS Secrets Manager

    aws secretsmanager get-secret-value --secret-id GRAPHQL_BASIC_AUTH_STRING --query "SecretString"

  2. Set the following variables in your .env file:

    HEADLESS_API_TOKEN=cM2XMtKpK3Lj
    GRAPHQL_BASIC_AUTH_STRING={Token retrieved from aws secrets manager}

  3. Ensure that the JSON Basic Authentication WordPress plugin is enabled.

    info

    Preview functionality will not work locally if you're pointing to the staging backend, since it's restricted using Basic Auth.

5. Build the local site​

At this point, you should now be able to build the site locally! Run this command:

organic-cli up

6. Restore Site Database​

In this step, we'll restore the latest site database backup from Amazon S3.

Download and restore the latest database backup from S3:

organic-cli restore-db-backup --latest
tip

Depending on the size of the database backup and the speed of your internet connection, this step may take some time to complete.

7. Frontend development steps​

  1. Navigate to the frontend folder.
  2. Run the following login command: 
    yarn npm login --scope orgnc
  3. Enter your GitHub username and GitHub access token created above as your password.
  4. Run yarn install to install frontend dependencies.
  5. Run yarn dev to run the frontend development server.

Two URLs should now be accessible:

  • https://lcl.example.com/ (used locally to see the frontend)
  • https://lcl-cms.example.com/wp/wp-admin/ (used locally to access the WordPress Admin)

Updating the Organic Dev tool​

To update or upgrade organic-dev-core, simply run:

aws codeartifact login --tool pip --domain organic --repository organic
pip3 install --upgrade organic-dev-core

It's important to do this periodically to get access to new features and ensure our documentation is correct for your version of the tool.

Additional Resources​

Your site's repository contains additional project-specific details in the form of READMEs. Please review the backend and frontend READMEs for additional management commands, procedures, and more.