--- title: "Environment" description: "This guide steps you through configuring a local development environment for the Sentry server on macOS." url: https://develop.sentry.dev/development-infrastructure/environment/ --- # Environment We primarily support development on macOS (arm64 only), but Linux (amd64) should be possible too. If you run into any problems on either platform, please open an issue on [devenv](https://github.com/getsentry/devenv/). ## [Setup](https://develop.sentry.dev/development-infrastructure/environment.md#setup) Begin by installing the `devenv` tool following [these instructions](https://github.com/getsentry/devenv#install). After installation, run `devenv bootstrap`, then open a new terminal and run `devenv fetch sentry`. When you're done with setup, you'll want to also review the [development workflow](https://develop.sentry.dev/development/workflow.md). ## [Keeping your environment up-to-date](https://develop.sentry.dev/development-infrastructure/environment.md#keeping-your-environment-up-to-date) First make sure your branch is rebased or remerged onto latest `master`. Running `devenv sync` (which runs `devenv/sync.py`) will bring your environment up-to-date (dependencies, migrations, etc.). You may also need to run `direnv allow` if you haven't already (sometimes it's easy to miss the prompt). Any issues? See [troubleshooting](https://develop.sentry.dev/development-infrastructure/environment.md#troubleshooting). ## [Running the Development Server](https://develop.sentry.dev/development-infrastructure/environment.md#running-the-development-server) The `devservices` ensure that you have all the services required for local development running. See the [devservices docs](https://develop.sentry.dev/development/devservices.md) for more information on managing services. When setting up `sentry`, execute the following command in the `sentry` folder: ```shell devservices up ``` After that, you can start the development server inside the `sentry` folder: ```shell devservices serve ``` Access it at (you'll have to wait a bit for webpack to finish). A superuser account should have been created for you during bootstrap - `admin@sentry.io` with password `admin`. You can create other users with `sentry createuser`. ##### Note When asked for the root address of the server, make sure that you use , as both protocol *and* port are required in order for DNS and some pages' URLs to be displayed correctly. ### [Frontend Only & Backend Only](https://develop.sentry.dev/development-infrastructure/environment.md#frontend-only--backend-only) Please refer to [Frontend Development Server](https://develop.sentry.dev/frontend/development-server.md) and [Backend Development Server](https://develop.sentry.dev/backend/development-server.md) for alternative ways to bring up the Sentry UI. ### [Enabling HTTPS](https://develop.sentry.dev/development-infrastructure/environment.md#enabling-https) Optionally, you may wish to run the development server over HTTPS, for certain situations (like testing JS APIs that require a secure context). First we will use [mkcert](https://github.com/FiloSottile/mkcert) to create and install a locally-trusted, development certificate and [Caddy](https://caddyserver.com/) as our reverse proxy. ```shell brew install mkcert brew install nss # if you use Firefox brew install caddy pnpm mkcert-localhost ``` Then we will run the reverse proxy as needed: ```shell pnpm https-proxy ``` After the server is running we can visit the dev server using `https` at port `:8003` instead of over `http` at `:8000`. ##### HTTP Strict-Transport-Security You might get into a situation where [HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) is enabled for your domain and you're unable to visit using `http` anymore. To clear the HSTS visit `chrome://net-internals/#hsts` in Chrome based browsers and use the "Delete domain security policies" form. ### [Ingestion Pipeline (Relay) aka Sending Events to your Dev Environment](https://develop.sentry.dev/development-infrastructure/environment.md#ingestion-pipeline-relay-aka-sending-events-to-your-dev-environment) [Relay](https://develop.sentry.dev/relay.md) and the ingest workers are not started by default. Follow the instructions below to start them so you can send events to your dev environment Sentry instance: * Set `SENTRY_USE_RELAY = True` in `~/.sentry/sentry.conf.py`. * Run `devservices up --mode ingest` to start the services Relay needs. (like for example Kafka) * Start your devserver (e.g. `devservices serve`). ## [Running the Getsentry Development Server](https://develop.sentry.dev/development-infrastructure/environment.md#running-the-getsentry-development-server) ##### Employees Only Only Sentry employees have access to getsentry. See also: [Sentry vs Getsentry](https://develop.sentry.dev/application/sentry-vs-getsentry.md) To set up and keep getsentry up to date, you need to run `devenv sync` inside `sentry` before you run `devenv sync` inside `getsentry`. `getsentry` depends on what commit `../sentry` is checked out to, so keeping your sentry repo up to date is important. Just like running `sentry` (see above), you can start the `devservices` using the following command in the `getsentry` repo: ```shell devservices up ``` To run tasks, you will also need to start taskbroker: ```shell # start just taskbroker devservices up --mode=taskbroker # start taskbroker and a background worker devservices up --mode=taskworker ``` If you use the `--mode` flag of devservices, any modes that started celery workers will now start taskbroker and a taskworker. After that, you can start the development server inside the `getsentry` folder: ```shell devservices serve ``` ##### Note You **cannot** have both sentry and getsentry devserver running at the same time. After the server warms up, access it at [http://dev.getsentry.net:8000](http://dev.getsentry.net:8000/). Using localhost won't work. Note that the **http** protocol is used, not **https**. If you encounter a certificate error while accessing it locally, it might be because your browser has remembered that `dev.getsentry.net` previously used the https protocol (possibly while running `pnpm dev-ui`) and is now redirecting all http requests to https. To resolve this, open the site in an **incognito window** of your browser. 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 by `dev.py` if it exists. To enable the ingest workers, follow the steps described [here](https://develop.sentry.dev/development-infrastructure/environment.md#ingestion-pipeline-relay) and run ```shell devservices serve ``` ## [Running siloed instances](https://develop.sentry.dev/development-infrastructure/environment.md#running-siloed-instances) By default `sentry devserver` will run a monolith mode application server. You can also run `devserver` with siloed application instances. Before you do, you need to [create split silo databases](https://develop.sentry.dev/backend/database-migrations.md#cloning-a-monolith-database). The devserver command supports `--silo` option that lets you create siloed instances. Any workers, consumers, or celery-beat processes will be started with the same silo mode. ```shell # Start control silo servers devservices serve --silo=control --celery-beat # Start region silo servers devservices serve --silo=region --celery-beat ``` Siloed servers have the following port assignments: * 8000 - Webpack * 8010 - Region silo webserver * 8001 - Control silo webserver In the above setup your local environment will use org slug domains, and send requests to `us.dev.getsentry.net` (region silo) and `dev.getsentry.net` (control silo). All requests will be proxied by webpack and forwarded to the appropriate server based on hostname. ### [Ngrok and siloed servers](https://develop.sentry.dev/development-infrastructure/environment.md#ngrok-and-siloed-servers) Refer to [ngrok docs](https://develop.sentry.dev/development/ngrok.md). ### [Siloed Django Shell](https://develop.sentry.dev/development-infrastructure/environment.md#siloed-django-shell) If you want to use a repl with silo modes active: ```shell # Start a control silo shell SENTRY_SILO_DEVSERVER=1 SENTRY_SILO_MODE=CONTROL getsentry django shell # Start a region silo shell SENTRY_SILO_DEVSERVER=1 SENTRY_SILO_MODE=REGION SENTRY_REGION=us getsentry django shell ``` ## [Troubleshooting](https://develop.sentry.dev/development-infrastructure/environment.md#troubleshooting) ### [Resetting the Database](https://develop.sentry.dev/development-infrastructure/environment.md#resetting-the-database) If you're experiencing persistent database issues (migrations failing, schema corruption, or incompatible migrations between branches), you can completely reset your local database using `make reset-db`. **Warning:** This will delete all local data in your database. ```bash make reset-db ``` This command will: * Drop the existing database * Create a new database * Run all migrations * Load initial data/fixtures *** **Problem:** `DoesNotExist: Subscription matching query does not exist` during getsentry devserver **Solution:** ```shell ./bin/mock-subscription ``` You can also set your local instance's org to use a business plan by running the following in getsentry: ```shell ./bin/mock-subscription --plan mm2_a_500k ``` *** **Problem:** `Error response from daemon: driver failed programming external connectivity on endpoint sentry-postgres-1 (e9e631ff7f32bd00052c25064c56609794a3b96da0dc04742f558e3ae659fa66): Bind for 127.0.0.1:5432 failed: port is already allocated` **Solution:** There is another process using the port. Try running `docker ps`. If you are currently running services through `sentry devservices`, you will need to stop them. ```shell sentry devservices down devservices up ``` Otherwise, check to see if you have another process running on the allocated port. ```shell lsof -i :5432 ``` Then, either end the process or kill it if you need to. *** **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 `devenv sync`. *** **Problem:** You see `Error occurred 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:** ```shell make build-platform-assets ``` *** **Problem:** You see `SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version 76` Or: ```shell 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 within 15.830 seconds (12 attempts.) ``` **Solution:** ChromeDriver needs to be updated. ```shell brew upgrade --cask chromedriver ``` *** **Problem:** You see `DoesNotExist: Subscription matching query does not exist` **Solution:** In getsentry, run the following to mock a subscription: ```shell ./bin/mock-subscription ``` *** **Problem:** You see something like `Error: No such container: sentry-postgres-1`, or you don't see `snuba-snuba-1`, `redis-redis-1`, `snuba-clickhouse-1`, and `kafka-kafka-1` listed under `COMMAND NAMES`. **Solution:** ```shell devservices up ``` *** **Problem:** You see something like `Error 61 connecting to 127.0.0.1:6379. Connection refused.` when running your dev server. **Solution:** Make sure your Docker services are running: ```shell docker ps ``` *** **Problem:** You use an Android emulator with a DSN pointing to localhost, and the events don't show up in your local Sentry instance. **Solution:** Change `localhost` to `10.0.2.2`. So, for example, change to . This is because localhost or `127.0.0.1` refers to the emulator's own loopback interface, not the loopback interface of the host machine. For more information see . *** **Problem:** Switching from Docker Desktop to Colima results in error `Failed to start service: Credentials store error: StoreError('docker-credential-desktop not installed or not available in PATH')` **Solution:** Remove the `credsStore` key in your `~/.docker/config.json` file. ## Pages in this section - [Assigned ports](https://develop.sentry.dev/development-infrastructure/environment/ports.md) - [Configuring U2F](https://develop.sentry.dev/development-infrastructure/environment/u2f.md)