Install with Docker

Warning: Bugsink is currently in private beta. You'll need an invite with a secret link to make the below work.

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. 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 Load

First, load the Bugsink Docker image (this assumes you’ve already downloaded the image via the secret link).

docker load --input path/to/bugsink.tar

The Dockerfile that generates the image is shown below for reference (you don’t need it, it’s already in the image):

ARG PYTHON_VERSION=3.12

# Build image: non-slim, in particular to build the mysqlclient wheel
FROM python:${PYTHON_VERSION} AS build

ARG WHEEL_FILE=wheelfile-not-specified.whoops

COPY dist/$WHEEL_FILE /wheels/
RUN --mount=type=cache,target=/var/cache/buildkit/pip \
    pip wheel --wheel-dir /wheels /wheels/${WHEEL_FILE} mysqlclient


# Actual image (based on slim)
FROM python:${PYTHON_VERSION}-slim

# ARGs are not inherited from the build stage; https://stackoverflow.com/a/56748289/339144
ARG WHEEL_FILE
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# mysqlclient dependencies; needed here too, because the built wheel depends on .o files
RUN apt update &amp;&amp; apt install default-libmysqlclient-dev -y

COPY --from=build /wheels /wheels
RUN --mount=type=cache,target=/var/cache/buildkit/pip \
    pip install --find-links /wheels --no-index /wheels/$WHEEL_FILE mysqlclient

COPY bugsink/conf_templates/docker.py.template bugsink_conf.py

RUN ["bugsink-manage", "migrate", "snappea", "--database=snappea"]

EXPOSE 8000

CMD [ "bugsink-server-unified", "bugsink-manage", "check", "--deploy", "--fail-level", "WARNING", "&&", "gunicorn", "--bind=0.0.0.0:8000", "--workers=10", "--access-logfile", "-", "bugsink.wsgi", "|||", "bugsink-runsnappea"]

Running the Container

The container can be run with the following command:

docker run -d \
  -e SECRET_KEY=&lt;...&gt; \  
  -e DATABASE_URL=mysql://[user]:[password]@[host]/[name] \
  -p 8000:8000 \
  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.

You may want to 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.

Initializing the Database

Before you can use Bugsink, you need to initialize the database schema and create an an initial user. This can be done by running the following commands (with the container running):

docker exec [container-id] bugsink-manage migrate
docker exec [container-id] bugsink 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!