Environment

This guide steps you through configuring a local development environment for the Sentry server on macOS. If you're using another operating system the instructions are still roughly the same, but we don't maintain any official documentation for anything else for now.

Clone the Repository

To get started, clone the repo at https://github.com/getsentry/sentry - or, your fork.

git clone https://github.com/getsentry/sentry.git
cd sentry

You're going to be working out of this repository for the remainder of the setup.

System Dependencies

You'll need to first install Xcode cli tools. (If you try running git or make, you'll get an xcrun error. Run xcode-select --install and follow the instructions.

Once you have Xcode installed, install Homebrew, and then run brew bundle --verbose to install the various system packages as listed in sentry's Brewfile.

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 menubar. 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 in your terminal. 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.

Build Toolchain

Sentry depends on Python Wheels, packages containing binary extension modules. We distribute these wheels for the following platforms:

• Linux compatible with PEP-513 (manylinux1)
• macOS 10.15.0 or newer

If your development machine does not run one of the above systems, you need to install the Rust toolchain. Follow the instructions at https://www.rust-lang.org/tools/install to install the compiler and related tools. Once installed, the Sentry setup will automatically use Rust to build all binary modules without additional configuration.

We generally track the latest stable Rust version, which updates every six weeks. Therefore, ensure to keep your Rust toolchain up to date by occasionally running:

rustup update stable

Python

We utilize pyenv to install and manage python versions. It should have already been installed earlier when you ran brew bundle.

To install the required versions of Python you'll need to run make setup-pyenv. 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.

If you're using bash, make sure your ~/.bash_profile contains the following:

source ~/.bashrc

Configure your shell to load pyenv:

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:

exec "$SHELL"

If it worked, running which python should result in something like /Users/you/.pyenv/shims/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:

source .venv/bin/activate

If everything worked, running which python should now result in something like /Users/you/sentry/.venv/bin/python.

JavaScript

We use volta to install and manage the version of Node.js that Sentry requires. To install Volta 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:

exec "$SHELL"

This works because the volta installer conveniently made changes to your shell installation files for your shell's startup script:

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:

node -v

Volta intercepts this and automatically downloads and installs the node and yarn versions in sentry's package.json.

Bootstrap Services

Source your virtual environment again (source .venv/bin/activate), then run make bootstrap. This will take a long time, as it bootstraps not only Sentry and its dependencies, but starts up related services, and runs database migrations.

The bootstrap command does a few things you'll want to know about:

• sentry init creates the baseline Sentry configuration in ~/.sentry/.
• sentry devservices up spins up required Docker services (such as Postgres and Clickhouse)
• sentry upgrade runs Postgres migrations, and will also prompt you to create a user. You will want to ensure your first user is designated as superuser.

Once this command has finished you'll have Sentry installed in development mode with all its required dependencies.

direnv

direnv automatically activates your virtual environment, sets some helpful environment variables for you, and performs some simple checks to make sure your environment is as expected (and tries its best to guide you if it isn't).

First, you should be done bootstrapping. Then, run brew install direnv and add the following snippet to the end of your startup script:

eval "$(direnv hook bash)"

And after doing that, reload your shell:

exec "$SHELL"

Any time the .envrc configuration changes (including the first time) you will be prompted to run direnv allow before any of the configuration will run. This is for security purposes and you are encouraged to inspect the changes before running this command.

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.

Setting up Getsentry

Now that you have sentry all set up, it's time to set up Getsentry. For information on the distinction between the two, refer to Sentry vs Getsentry. After setting it up, you'll also want to read about the development workflow here.

Let's start off by cloning the getsentry repository to be adjacent with your sentry repository:

# Go to where you have sentry and clone getsentry.
cd /path/to/sentry
cd ..
git clone git@github.com:getsentry/getsentry.git

It's necessary to keep getsentry in an adjacent directory (it's expected by install-py-dev in the getsentry Makefile). For example, if you did a ls ~/code you'd see something like:

sentry/   getsentry/

Next, create a virtual environment just like how you did with Sentry earlier.

Then, run make bootstrap and follow any additional instructions that come up.

If all went well, then you can start the development server:

getsentry devserver --workers

Note that you cannot have both sentry and getsentry devserver running at the same time.

After the server warms up for a little while, you should be able to access it at http://dev.getsentry.net:8000.

If you see DoesNotExist: Subscription matching query does not exist in your dev server, run the following in getsentry:

./bin/mock-subscription

You can set your local instance's org to use a business plan by running the following in getsentry:

./bin/mock-subscription <org_slug> --plan mm2_a_500k

Troubleshooting

You might also be interested in troubleshooting CI.

Problem: something like pkg_resources.DistributionNotFound: The 'some_dependency<0.6.0,>=0.5.5' distribution was not found and is required by sentry

Solution: Your virtualenv needs to be updated. run make install-py-dev.

Problem: You see Error occured while trying to proxy to: dev.getsentry.net:8000/

Solution: You likely need to upgrade your Python dependencies. Go to the git root directory and run make install-py-dev.

Problem: Module not found: Error: Can't resolve 'integration-docs-platforms'

Solution:

make build-platform-assets

Problem: SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version 76

Also, another symptom indicating you need to upgrade chromedriver:

Traceback (most recent call last):
  File "/Users/joshua.li/dev/sentry/sentry/src/sentry/utils/pytest/selenium.py", line 344, in browser
    driver = start_chrome(**chrome_args)
  File "/Users/joshua.li/dev/sentry/sentry/src/sentry/utils/retries.py", line 41, in execute_with_retry
    return retrier(functools.partial(fn, *args, **kwargs))
  File "/Users/joshua.li/dev/sentry/sentry/src/sentry/utils/retries.py", line 85, in __call__
    error,
RetryException: Could not successfully execute <functools.partial object at 0x10f31e7e0> within 15.830 seconds (12 attempts.)

Solution:

brew cask upgrade chromedriver

Problem:

--- snip ---
00:51:27 server  | ImportError: cannot import name _remove_dead_weakref
00:51:27 server  | unable to load app 0 (mountpoint='') (callable not found or import error)

This is caused by uwsgi running the wrong version of python. When starting up, you'll see something like

uwsgi socket 0 bound to TCP address 127.0.0.1:8889 fd 3
Python version: 2.7.10 (default, Feb 22 2019, 21:17:52)  [GCC 4.2.1 Compatible Apple LLVM 10.0.1 (clang-1001.0.37.14)]
Set PythonHome to /Users/dfuller/code/sentry/.venv

The python version here should be 2.7.16, but will be a lower version, likely your system python. This is because uwsgi was compiled against a stale python and the resultant wheel has been cached by pip.

Solution:

In your sentry virtualenv:

pip uninstall uwsgi
pip install --no-cache-dir uwsgi

Problem: DoesNotExist: Subscription matching query does not exist

Solution: In getsentry run the following to mock a subscription:

./bin/mock-subscription <org_slug>

Problem: Something like Error: No such container: sentry_postgres

Solution: Review the bootstrap services section or spin up Docker services with:

sentry devservices up