Setting up your local environment
Learn how to set up your local Braze Docs environment, so you can make complex or multi-page changes.
Prerequisites
If you haven’t already, complete the steps for Contributing to Braze Docs.
Setting up your local environment
Step 1: Get the required software
At a minimum, you need a terminal, a text editor, and a ruby version manager. If you’re not sure where to start, see the following.
| Type | Product | Description |
|---|---|---|
| Git GUI | GitHub Desktop | A graphical user interface (GUI) you can use to run Git commands, instead of typing commands in the terminal. |
| Terminal | Wezterm | A terminal emulator that allows you to run commands and interact with the Braze Docs repository from the commandline. If you're using a Windows operating system, you'll also need to install Windows Subsystem for Linux (WSL). |
| Terminal extension | Windows Subsystem for Linux (WSL)* | WSL lets you install a Linux subsystem and run Unix-like commands on your Windows operating system. If you're contributing from a Windows operating system, we recommend installing WSL, so you can use any Unix-like command mentioned in the docs. * Only available for Windows. |
| Package manager | Homebrew | A package manager that allows you to install and manage the various command-line interface (CLI) tools used for contributing to Braze Docs. |
| Ruby version manager | rbenv | A Ruby version manager that allows you to install and manage the required Ruby version for Braze Docs when you're setting up your local environment. To use a different Ruby version manager, see Ruby's supported version managers. |
| Text editor | Visual Studio Code (VS Code) | A full-featured text editor by Microsoft that allows you to edit any file in the Braze Docs repository. To improve your experience, be sure to install the following plugins: |
| Text editor | Intellij's IDEA Community Edition | A full-featured text editor by Intellij that allows you to edit any file in the Braze Docs repository. To improve your experience, be sure to install the following plugins: |
As of writing, all software is free of cost. If you find that a product is no longer free, please let us know.
Step 2: Create an SSH key
Next, create an SSH key for your GitHub account. Note that if you’re using WSL, be sure to follow the Linux instructions to create your SSH key.
Step 3: Clone your forked repository
Double-check that you forked the repository, before trying to clone it locally.
In GitHub, open your forked repository, then select Code > SSH > Copy.
In your terminal, open your home directory, then clone the Braze Docs repository.
1
2
cd ~
git clone [email protected]:braze-inc/braze-docs.git
Step 4: Add a remote for braze-inc/braze-docs
To ensure that your changes are pushed to the official Braze Docs repository, instead of your fork, you’ll need to set up a new remote in Git.
1
2
cd ~/braze-docs
git remote add upstream [email protected]:braze-inc/braze-docs.git
To verify that your new upstream remote was added successfully, list your remotes using the remote command’s -v option.
1
2
3
4
5
$ git remote -v
origin [email protected]:internetisaiah/braze-docs.git (fetch)
origin [email protected]:internetisaiah/braze-docs.git (push)
upstream [email protected]:braze-inc/braze-docs.git (fetch)
upstream [email protected]:braze-inc/braze-docs.git (push)
Step 5: Install Ruby
To generate a local site preview, you’ll need Ruby version 3.3.0 installed. In the terminal, open braze-docs and check for Ruby version 3.3.0.
1
2
cd ~/braze-docs
ruby --version
If this version isn’t installed, use a supported version manager to install Ruby version 3.3.0. For example, using rbenv:
1
rbenv install 3.3.0
Step 6: Install dependencies
Next, install the dependencies for Braze Docs. These are small programs used to generate your local Braze Docs site.
1
bundle install
Step 7: Start your local server
To verify your installation and start your local docs server on localhost http://127.0.0.1:4000, run:
1
2
3
4
5
6
7
8
9
# for 'en' language:
rake
# for other langauges:
rake es
rake fr
rake ja
rake ko
rake pt_br
To stop your server, reopen the terminal and press Control+C.
Next steps
If you’re new to Git or docs-as-code, start with our tutorial: Your first contribution. Otherwise, check out one of the following.
Edit this page on GitHub