Get Your Own Sentry Playground

Sentry is an amazing tool for error tracking and monitoring. You install the SDK in your codebase, configure it, and *tada*, all your runtime errors are now sent to their backend.

However, it can be tricky to get the setup right at times.

To test out the integration, wouldn’t it be cool if you had god-mode access to Sentry?

Let me take you through WHY you would want to have your very own local Sentry instance, HOW to get one and WHAT you can do with it.

This article deals with version 20.9.0 of Sentry.

Meerkat on the lookout for your errors, Photo by Lance Anderson on Unsplash

A local Sentry instance, WHY?

This allows you to clean everything up nice and quick.

You can run the specific Sentry version you have at work to reproduce whatever problem you’re facing.

If you want to test something with the full admin rights (which you probably don’t have on the instance you would use in production), a local Sentry instance is perfect! That should help you decide whether your production instance has some limitations or your setup is broken.

You don’t want to create a throwaway account on Sentry.io. This is kind of messy and you wouldn’t want someone to create fake accounts on your service. What’s more, they open-sourced their tool for anyone to self-host so let’s use that instead!

Install your on premise Sentry

To install and run Sentry locally, we will use their open-source getsentry/onpremise GitHub repository.

At the time of writing and for the rest of this article, we will use version 20.9.0 of Sentry.

Prerequisites

Sentry needs to have Docker 19.03.8+ and Docker Compose 1.24.1+.
It is also quite greedy in terms of RAM: you will need at least 2400MB of RAM. Installing Docker and Docker Compose is out of the scope of this article, but here are some links to help you:

• How to Install and Use Docker on Ubuntu 20.04, Digital Ocean
• Install Docker Compose, Docker documentation

Clone the repository

Let’s clone the onpremise repository and go into the releases/20.9.0 branch.

$ git clone [email protected]:getsentry/onpremise.git Sentry-onpremise
$ cd Sentry-onpremise
$ git checkout releases/20.9.0

Install and create a user account

Once inside the directory and with the correct branch checked out, we can run the installation script:

$ ./install.sh

This will take some time because Docker needs to pull a lot of Docker images, set them up (for example run database migrations after creating the databases). You will eventually be prompted with:

Would you like to create a user account now? [Y/n]:

After pressing Y + ENTER, you can choose whatever email and password:

Would you like to create a user account now? [Y/n]: Y
Email: [email protected]
Password:
Repeat for confirmation:
User created: [email protected]
Added to organization: sentry
...
----------------
You're all done! Run the following command to get Sentry running:

  docker-compose up -d

Congrats, you now have a local Sentry setup. Let’s run it!

First run of your instance 🏎️

Following the ending instructions from the installation script, you need to run

$ docker-compose up -d

from the same directory to get Sentry started. Docker Compose will print out to the console which Docker containers it’s creating, and as long as “done” is written after every line, you’re good to continue.

By default, Sentry’s UI lives on port 9000, so you can go ahead and open http://localhost:9000 in your favorite browser (it’s Firefox, right?). You will be greeted with this login screen.

After entering my very secure credentials (okay, it was [email protected] and 123456, but hush, it’s a secret!), another screen shows up to configure the instance. You can leave the defaults as they are, and decide whether you want to send usage statistics to Sentry.io or not.

Now onto the exciting part: let’s create your first Sentry project.

Pay no heed to the warning, it’s because the Sentry workers responsible to process your error reports have indeed not run yet.

Let’s select JavaScript.

You will see the following instructions.

The easiest way to test if your installation works properly is to use this HTML template; just fill in the DSN assigned to your project in the REPLACE_ME_PLEASE placeholder.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <script
      src="https://browser.sentry-cdn.com/5.23.0/bundle.tracing.min.js"
      integrity="sha384-lSZkoLgJeNT+V/zBEZAchPik9VPNr9wvgAY6mwoMK5SO/cMsK/whVXKKdQOL1oiw"
      crossorigin="anonymous"
    ></script>
    <script>
      Sentry.init({
        dsn: 'REPLACE_ME_PLEASE',
        integrations: [new Sentry.Integrations.BrowserTracing()],
        tracesSampleRate: 1.0,
      })
    </script>
  </head>
  <body>
    <button onclick="breakTheInternet()">Break the Internet</button>
  </body>
</html>

You can now open this file in your browser to test this out. Make sure that your extensions did not block the loading of Sentry’s SDK or it’s not going to work.

On to the magical ✨ moment: let’s break the Internet!

A POST request was initiated to localhost:9000, that’s a good start!

Verify that it shows up in Sentry.

All good then, your local Sentry instance is now functional and yours to play with.

If you don’t want to keep it running all the time, you can run docker-compose down (from the same folder) whenever you need to shut it down, and docker-compose up -d to have it back on again.

Parting words

We can now test pretty much anything with full access to the permissions. I personally tested out that my Next.js setup at work was correctly uploading sourcemaps, creating a Sentry release as well as associate the commits to that release without touching the production instance.

What’s more, we uncovered in the process that our sourcemaps were not being processed correctly by our Sentry instance because of some permissions not being set up correctly between the containers. 🤩

I hope this post was helpful and I would love to hear from you!

What will you use your local Sentry playground for?