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.

Docker installation​

Download and install the latest Docker Desktop app.

Homebrew Bulk Install Command​

brew install -q \
     awscli \
     mkcert \
     node \
     nss \
     python3 \
     yarn

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 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 $HOME/organic-dev-venv && source $HOME/organic-dev-venv/bin/activate
aws codeartifact login --tool pip --domain organic --repository organic
pip install organic-dev-core

Add path to isolated env to your shell start script:

echo 'export PATH="$PATH:$HOME/organic-dev-venv/bin"' >> ~/.zshrc
( or ~/.bashrc for linux)

3. 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-token-here with an Artifactory token provided to you by Organic Support. Contact Organic Support for a token if you don't have one.
  5. 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={Token retrieved from repo}
    GRAPHQL_BASIC_AUTH_STRING={Token retrieved from aws secrets manager}

    You can find HEADLESS_API_TOKEN by viewing the following file: orgnc/your-repo-name/frontend/kubernetes/configmap.yaml or orgnc/your-repo-name/frontend/kubernetes/overlays/production/configmap.yaml

  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.

4. 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.

5. Build and run the local backend site​

You can now run the site locally! organic-cli up is the command to use each time you want to start a single site for development.

Note: The first time you run organic-cli up for a given site, you will need to include the --build flag:

organic-cli up --build

In the future when you need to bring a site up, simply run:

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 token as username and the Artifactory token provided to you 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.

Get the application logs​

You can get the latest application logs from staging or production environment by running the following cmd:

organic-cli get-logs --env <staging|production> --app_type <backend|frontend>
example: organic-cli get-logs --env staging --app_type backend

Notes:

  • This command returns the most recent access log records for the last 10 minutes.
  • The amount of delivered record can be large for production environment.
  • There is a maximum 5 minutes delay for the logs delivering from kubernetes containers to the logs storage.

Upload local DB to staging​

You can upload the local DB to staging environment by running the following command:

organic-cli upload-local-db

Notes:

  • This command makes full backup of the local WP database, uploads it to S3 and and replaces the staging DB with it.
  • Please keep in mind that this process means full DB replacement, so all the previous data in staging DB will be lost, so it might be a good idea to a make a staging backup first using organic-cli make-backup.