--- 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 | Sentry Docs 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-infrastructure/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-infrastructure/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/development-infrastructure/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/ingestion/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-architecture/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/application-domains/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-infrastructure/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)