Install with Docker

Bugsink is available as a Docker image, making it easy to run in any environment that supports Docker containers. Images are available for both the amd64 and arm64 architectures.

There are two main ways to run Bugsink with Docker:

  • Quick throw-away instance: Start a container with SQLite as the database, and no data persistence. This is useful to quickly try out Bugsink.

  • External database: Set up a MySQL database outside the Docker container, and pass the connection details to the Bugsink container. This is useful for any setup where you want to retain data.

This guide assumes you are familiar with Docker and have it installed on your system.

Quick throw-away instance

Use the following command to quickly start a throw-away instance of Bugsink:

docker pull bugsink/bugsink:latest

docker run \
  -e SECRET_KEY=ezQmX5s07PUNt17IoHYjtfUi5fnNukdKaRoLIPkUSriNhtpRtl \
  -e CREATE_SUPERUSER=admin:admin \
  -e PORT=8000 \
  -p 8000:8000 \
  bugsink/bugsink

Visit http://localhost:8000/ to visit Bugsink. The default username and password are admin.

Now, you can set up your first project and start tracking errors.

Note that in this setup, the SQLite database is used, and all data will be lost when the container is removed. If you don’t want that, read on to learn how to use MySQL instead.

Running with MySQL

The quick setup above uses SQLite as the database, which means all data will be lost when the container is removed. If you want to retain data, you can use a MySQL database instead.

Set up a MySQL database outside the Docker container, and pass the connection details to the Bugsink container using the DATABASE_URL environment variable:

docker run \
  -e SECRET_KEY=ezQmX5s07PUNt17IoHYjtfUi5fnNukdKaRoLIPkUSriNhtpRtl \
  -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. The one above is generated on the fly, just for you, but you can also generate your own 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. Set the user, password, host, and name to match your MySQL setup.

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

Note: This step is not needed if you created the superuser inline using CREATE_SUPERUSER; on the flip side: if you copy/pasted the command, you might want to change the password or remove the user admin from the database.

Reverse Proxy

If you are running in production, strongly consider setting up a reverse proxy, such as Nginx, to handle incoming requests and manage SSL certificates. Make sure to:

  • Set the environment variable BEHIND_HTTPS_PROXY to True to make Dockerized Bugsink aware of the proxy.
  • Set Proxy Headers accordingly.

SQLite on Docker Volumes

As noted in the quick throw-away instance above, SQLite is used by default when running Bugsink in Docker and not specifying a DATABASE_URL.

You may wonder why SQLite is only recommended for throw-away instances. After all, SQLite is a great database, and it is actually the recommended database for Bugsink when running in non-containerized environments.

The way to do this in Docker would be: use Docker volumes to persist the SQLite database. However, there is a catch: Docker volumes do not provide the necessary guarantees for SQLite in WAL-mode, which is the mode Bugsink uses. Hence: not recommended.

Next Steps

Here are some additional steps you can take to further customize your Bugsink setup:

  • The above is enough to get Bugsink running, but you may want to set additional environment variables to configure the application further.

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

  • 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!