Install with Docker

Note: Bugsink is currently in Public Beta; most things should "just work", but there may be some rough edges. In particular, usage with the Python SDK is the most tested and stable, while the others have varying levels of stability. If you encounter any issues, please let us know!

If you prefer using Docker, Bugsink can be easily containerized. This method is ideal for testing and deployment across various environments. Depending on your setup, you can run Bugsink using Docker CLI, Docker Compose, or even Kubernetes. Images are available for both the amd64 and arm64 architectures.

Below, I’ll cover the basics, but feel free to adapt it to your preferred method. This guide assumes you are familiar with Docker and have it installed on your system.

MySQL vs. SQLite

There are two primary ways to run Bugsink with Docker:

MySQL: This option requires additional setup outside the Docker container to run a MySQL database. The benefit is that your data is retained even after the container is removed.
SQLite: This option is more straightforward since the SQLite database is stored inside the container. However, all data will be lost once the container is removed.

Docker Pull & Run

First, pull the Bugsink Docker image:

docker pull bugsink/bugsink:latest

The container can be run with the following command:

docker run -d \
  -e SECRET_KEY=[...] \  
  -e DATABASE_URL=mysql://[user]:[password]@[host]/[name] \
  -p 8000:8000 \
  bugsink/bugsink

Replace the placeholders ([...]) with your specific configurations.

SECRET_KEY must be a random string, at least 50 characters long. You can generate one using e.g. openssl rand -base64 50.
DATABASE_URL should be a valid database URL for a MySQL database which you have set up, and to which the Bugsink container has access.

The above is enough to get Bugsink running, but you may want to set additional environment variables to configure the application further. Refer to the production installation guide for more hints on which environment variables to set. Alternative, refer to the settings overview for a full list of available environment variables.

Running with SQLite

If you don’t want to set up a MySQL database, you can use SQLite instead. This gets you up and running quickly, but all data will be lost when the container is removed.

Other than that the SQLite setup is very much production-ready, and is the default setup for non-containerized installations.

To run with SQLite, simply leave the DATABASE_URL environment variable unset, and Bugsink will default to using SQLite.

Resist the temptation to mount a volume and have the SQLite database stored on that volume: SQLite and Docker’s volume system don’t play well together.

Creating a Superuser

Before you can use Bugsink, you need to create an an initial user. This can be done by running the following commands (and passing in the container ID and environment variables as needed):

docker exec -it  \
  -e DATABASE_URL=mysql://[user]:[password]@[host]/[name] \
  [container-id] \
  bugsink-manage createsuperuser

Accessing Bugsink

Once the container is running, you can access Bugsink by visiting http://localhost:8000 in your browser. You can log in with the superuser account you created earlier.

Next Steps

With Bugsink running in Docker, you can now connect it to your applications to start collecting crash reports.

If you are running in production, strongly consider setting up a reverse proxy, such as Nginx, to handle incoming requests and manage SSL certificates. Notes on how to do this can be found in the production installation guide. Set the environment variable BEHIND_HTTPS_PROXY to True to make Bugsink aware of

You can also explore more advanced configurations, such as using Docker Compose or Kubernetes for orchestration. Feel free to customize and expand based on your environment!