This guide steps you through configuring a local development environment for the Sentry server on macOS and Linux. If you're using another operating system (Plan 9, BeOS, Windows, …) the instructions are still roughly the same, but we don't maintain any official documentation for anything else for now.
Read about known issues in the troubleshooting section.
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.
You'll need to first install Xcode CLI tools. Run this command and follow the instructions:
Install Homebrew, and then the following command to install
the various system packages as listed in Sentry's
brew bundle --verbose
On Docker Desktop, you can adjust the memory limits by going to:
Preferences > Resources > Memory
Or through CLI:
# quit Docker if its running osascript -e 'quit app "Docker"' # check what the default is configured currently cat /Users/`id -un`/Library/Group\ Containers/group.com.docker/settings.json | grep "memoryMiB" # increase configured memory to something reasonable sed -i .bak 's/"memoryMiB":.*/"memoryMiB": 7168,/g' /Users/`id -un`/Library/Group\ Containers/group.com.docker/settings.json # check configuration cat /Users/`id -un`/Library/Group\ Containers/group.com.docker/settings.json | grep "memoryMiB" # start up docker with next steps
docker (which brew has already installed for you under
/Applications/Docker.app) needs some manual
intervention. You can run this command to set it up automatically for you:
open -g -a Docker.app
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.
Sentry depends on Python Wheels (packages containing binary extension modules), which, we distribute for the following platforms:
- Linux compatible with PEP-513 (
- macOS 10.15 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
We utilize pyenv to install and manage Python versions. It got
installed when you ran
To install the required version of Python you'll need to run the following command. This will take a while, since your computer is actually compiling Python!
fish users will need to manually set some of the environment variables. This only needs to be done once.
set -Ux PYENV_ROOT $HOME/.pyenv # fish >=3.2.0 fish_add_path $PYENV_ROOT/bin # fish <3.2.0 set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths
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:
After this, if you type
which python, you should see something like
/usr/bin/python. This is because the following has been added to your start up script:
Given that the bash instructions vary greatly based on the user's configuration, it is recommended to visit https://github.com/pyenv/pyenv#installation for instructions on how to set up Bash.
You're now ready to create a Python virtual environment. Run:
python -m venv .venv
And activate the virtual environment:
If everything worked, running
which python should now result in something like
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:
This works because the volta installer conveniently made changes to your shell installation files for your shell's startup script:
export VOLTA_HOME="$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,
Volta intercepts this and automatically downloads and installs the node and yarn versions in sentry's
Source your virtual environment again (
source .venv/bin/activate), then run
make bootstrap. This will take a long time,
as it bootstraps Sentry, its dependencies, starts up related services and runs database migrations.
bootstrap command does a few things you'll want to know about:
sentry initcreates the baseline Sentry configuration in
sentry devservices upspins up required Docker services (such as Postgres and Clickhouse)
sentry upgraderuns 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.
Note: This command is meant to be run only once. To bring your dependencies up-to-date use
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). This happens every time you change directories into sentry.
First, you should be done bootstrapping. Then, run
brew install direnv and add the following snippet to the end of your
eval "$(direnv hook bash)"
And after doing that, reload your shell:
Any time the
.envrc configuration changes (including the first load) 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.
If you want to personalize your environment variables, you can do so by creating a
.env file. This file is
git, thus, you will not be able to leak it into one of your PRs.
make direnv-help will list all of the latest supported environment variables. Using
SENTRY_DEVENV_NO_REPORT as an example,
to enable that setting you would insert
SENTRY_DEVENV_NO_REPORT=1 into your
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 fewer 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.
Some services are not run in all situations, among those are Relay and the ingest workers. If you need
a more production-like environment in development, you can set
~/.sentry/sentry.conf.py. This will launch Relay
as part of the
Additionally you can explicitly control this during
devserver usage with the
--no-ingest flags. The
command will not update Relay automatically in that case, to do this manually run:
sentry devservices up --skip-only-if relay sentry devserver --workers --ingest
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 to your
# Go to where you have sentry and clone getsentry. cd /path/to/sentry cd .. git clone firstname.lastname@example.org:getsentry/getsentry.git
It's necessary to keep getsentry in an adjacent directory (it's expected by
various make targets in the getsentry Makefile). For example, if you
ls ~/code you'd see something like:
Next, create a virtual environment just like how you did with Sentry earlier.
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: 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:
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
If you need to overwrite configuration options for your local
environment. You can create
getsentry/conf/settings/devlocal.py and put the
configuration option overrides there. This module will be automatically imported
dev.py if it exists.
You might also be interested in troubleshooting CI.
Problem: You see an error that mentions 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
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
Module not found: Error: Can't resolve 'integration-docs-platforms'
Problem: You see
SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version 76
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.)
ChromeDriver needs to be updated.
brew upgrade --cask chromedriver
--- 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.
In your sentry virtualenv:
pip uninstall uwsgi pip install --no-cache-dir uwsgi
Problem: You see
DoesNotExist: Subscription matching query does not exist
Solution: In getsentry, run the following to mock a subscription:
Problem: You see something like
Error: No such container: sentry_postgres
Solution: Review the bootstrap services section or spin up Docker services with:
sentry devservices up