Setting up Your Development Environment
Follow the Docker file in the repository but instead of creating and installing a wheel, install the package in editable mode (
pip install . -e).
To get started, fork the repo at https://github.com/getsentry/sentry. Clone your forked repo and go into it:
git clone https://github.com/<your github username>/sentry.git cd sentry
macOS - System Dependencies
Install Homebrew, and then run
brew bundle to install the various system packages as listed in sentry’s
One thing that requires manual attention is
docker, which should have just been installed. Open up Spotlight, search for “Docker” and start it. You should soon see the docker icon in your macOS toolbar. Docker will automatically run on system restarts, so this should be the only time you do this.
You can verify that docker is running by running
docker ps. If it doesn’t error with something like
Error response from daemon: dial unix docker.raw.sock: connect: connection refused, you’re good to continue.
macOS - Python
Unfortunately, homebrew recently removed Python 2. While some versions of macOS ship with Python 2, it’s recommended to not use the system’s installation. Sentry also requires a specific version of Python, as shown in the file
.python-version, and this may differ from the system’s python.
We recommend using pyenv to install and manage python versions. It should have already been installed earlier when you ran
You should be able to install python by running
pyenv install. This will take a while, since your computer is actually compiling python!
After this, if you type
which python, you should see something like
/usr/bin/python… this means
python will resolve to the system’s python. You’ll need to make some manual changes to your shell initialization files, if you want your shell to see pyenv’s python.
Make sure your
~/.bash_profile contains the following:
eval "$(pyenv init -)"
Once that’s done, your shell needs to be reloaded. You can either reload it in-place, or close your terminal and start it again and cd into sentry. To reload it, run:
PATH="" exec /bin/bash -l
If it worked, running
which python should result in something like
macOS - NodeJS
Sentry also requires a specific version of NodeJS. Like pyenv, we recommend using volta to install and manage node versions. Unfortunately, brew doesn’t provide volta yet, but installation is quite easy. Run:
curl https://get.volta.sh | bash
The volta installer will tell you to “open a new terminal to start using Volta”, but you don’t have to! You can just reload your shell like before:
PATH="" exec /bin/bash -l
This works because the volta installer conveniently made changes to your shell installation files for you, but it’s good to verify. Your
~/.bash_profile should be the same, but make sure your
~/.bashrc looks like this:
eval "$(pyenv init -)" export VOLTA_HOME="~/.volta" grep --silent "$VOLTA_HOME/bin" <<< $PATH || export PATH="$VOLTA_HOME/bin:$PATH"
Now, if you try and run
volta, you should see some help text, meaning volta is installed correctly. To install node, simply run:
Volta intercepts this and automatically downloads and installs the node version in sentry’s
macOS - Python (virtual environment)
You’re now ready to create a python virtual environment. Run:
python -m pip install virtualenv python -m virtualenv .venv
And activate the virtual environment:
If everything worked, running
which python should now result in something like
macOS - Final Bootstrap
The last step is to run
make bootstrap. This will take a long time, as it basically installs sentry and all of its dependencies, starts up external services, and preps databases.
macOS - direnv (optional, but recommended)
We have a direnv configuration for Sentry. It automatically sets some helpful environment variables for you, automatically activates your virtual environment, and does some simple state checking to guide you towards the expected development environment.
To install it, run
brew install direnv. You’ll want to add this to the end of your
eval "$(direnv hook bash)"
And after doing that, reload your shell:
PATH="" exec /bin/bash -l
Now, direnv should automatically execute (or you might need to type
direnv allow). If you’ve followed this guide correctly, it should succeed.
Running the Development Server
Once you’ve successfully stood up your datastore, you can now run the development server:
sentry devserver --workers
If you are developing for aesthetics only and do not rely on the async workers, you can omit the
--workers flag in order to use less system resources.
If you would like to be able to run
devserver outside of your root checkout, you can install
webpack globally with
npm install -g webpack.
When webpack finishes processing, you can find a login prompt for the user account you previously created at http://localhost:8000. From there, you are free to browse the website as an administrator.
Staging Your Changes
You’ve made your changes to the codebase, now it’s time to present them to the Sentry developers. It is recommended to first run the test suite locally in order to find any linting, syntax, or integration before you post a Pull Request.
Running the Test Suite Locally
make test-js or
make test-python to run the test suite with the corresponding language. There are also other
test- targets, refer to the
Generally, testing is left to continuous integration (travis), or you may directly invoke testing utilities if you need finer granularity e.g.