Settings

This page describes the settings that you can use to configure your Bugsink instance. Bugsink’s settings are typically configured in a file called bugsink_conf.py. If you have followed one of the installation guides, you will have generated a configuration that makes sense for your particular setup. You will notice that some of the variable-names here are actually nested, i.e. are inside a dictionary called BUGSINK or SNAPPEA. Just change the variables where they are and you’re good.

In the Docker setup, Bugsink is more typically configured using environment variables. The names of these settings are the same as in bugsink_conf.py, but some parsing of strings is done to make it easier to set them in a Docker environment.

Changing settings in bugsink_conf.py will require a restart of the webserver and (if you’re running that) the snappea worker. Changing settings using environment variables will require a restart of the webserver.

If you are logged into your Bugsink instance as a superuser, you can inpect the values of your settings by going to http[s]://your.bugsink/settings/

Your “site”

Your particular instance of self-hosted Bugsink is called a “site”. To customize the name, and to let Bugsink know about itself, you need to set the following settings:

  • SITE_TITLE: Customizable title for the Bugsink site. This is useful when you have multiple instances of Bugsink running. Default: "Bugsink". Examples: "[Company name] Bugsink", "Bugsink (Staging)", "Bugsink (Local dev)".

  • BASE_URL: Base URL where the Bugsink instance is hosted. Bugsink uses this to construct links to itself, e.g. when DSNs are created, or in various notifications. Default: "http://localhost:8000". Example: "https://bugsink.yourcompanyname.com". The domain name is is also used to set the ALLOWED_HOSTS setting in Django, i.e. only requests with this domain name will be accepted.

Database

The preferred database for Bugsink is SQLite. The main point of configuration is the (nested) value for DATABASES["default"]["NAME"], which should point to a file.

MySQL is also supported; mainly with an eye on Dockerized deploys and other environments where you already have a MySQL database running or where it is easier to provision one. For Docker, the MySQL database can be configured using a single DATABASE_URL connection string, which is in the following format:

"mysql://user:password@host:port/database_name"

HTTPS and Proxy settings

In production setups, you are strongly encouraged to use HTTPS. In a typical setup this is achieved by putting a proxy in front of the gunicorn server that’s actually running Bugsink.

You need to configure the proxy to set the correct headers.

Bugsink itself must also know that it’s behind a proxy and that the proxy is taking care of HTTPS, by either:

  • setting the environment variable BEHIND_HTTPS_PROXY to True in the Docker setup. (This single environment variable set the below settings for you, but you still need to configure your proxy accordingly)

or, when configuring bugsink_conf.py, by setting the following settings:

  • SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') – and make sure to set up your proxy to set the X-Forwarded-Proto header to https when the request is made over HTTPS.

  • SESSION_COOKIE_SECURE and CSRF_COOKIE_SECURE should be set to True.

  • USE_X_REAL_IP should be set to True – and make sure to set up your proxy to set the X-Real-IP header to the client’s IP address. (In Nginx, you can use $remote_addr)

Note: X-Forwarded-For can be used as an alternative to X-Real-IP. Details can be found in our documentation on proxy headers.

Email

Bugsink uses email to send notifications about issues, and for administrative purposes such as password reset emails. In production-like environments, you should set up email settings. If you don’t, Bugsink will still work, but you won’t receive any emails.

If you use an email server already, by all means use those settings. If you don’t, we recommend using a transactional email service like Postmark. Bugsink is all-in on self-hosting where possible, but for email we recommend using a service that specializes in it.

Email is configured using SMTP. The following settings are required:

  • EMAIL_HOST: Host to use for sending emails. Example: "smtp.example.com".

  • EMAIL_HOST_USER: Username to use for the SMTP server.

  • EMAIL_HOST_PASSWORD: Password to use for the SMTP server.

  • EMAIL_PORT: Port to use for the SMTP server. Default: 587.

  • EMAIL_USE_TLS: Use a TLS (secure) connection when sending email. Default: "True".

  • DEFAULT_FROM_EMAIL: Default “from” email address for the emails. The default value of "Bugsink <bugsink@example.org>" is not your actual email address, so you should change this to avoid bounces or spam-problems.

User registration and permissions

If you’re running Bugsink for yourself only, set SINGLE_USER to True. This disables all multi-user functionality, i.e. user-registration, teams and project-membership.

In multi-user setups, the openness of your Bugsink instance is controlled by the USER_REGISTRATION setting. It can be set to one of the following values:

  • CB_ANYBODY - Anybody can sign up and start using Bugsink. New users can sign up and start using your app without any intervention from you: on the login page, they can click the “Sign up” link and create an account. This setting is useful in environments where access to Bugsink is guarded by other means, such as a Firewall, VPN or IP whitelisting. In such environments, allowing anybody to sign up will make it easier for both you and your users. This is (obviously) a dangerous setting if your Bugsink instance is accessible from the public internet.

  • CB_MEMBERS - Any existing user can invite new users to join, by entering their email address when adding members to a team or project.

  • CB_ADMINS - Only admins can invite new users to join, i.e. when inviting members to a team or project, only users with the “Admin” role can enter an email address that is not already registered.

  • CB_NOBODY - User registration is disabled entirely. (Note that this is slightly less far-reaching than setting SINGLE_USER to True, which disables all multi-user functionality, because it does not remove already-registered users from the system)

Further settings control the user registration process:

  • USER_REGISTRATION_VERIFY_EMAIL - If set to True, new users must verify their email address before they can log in. This is useful for ensuring that users provide a valid email address, and for preventing spam accounts.

  • USER_REGISTRATION_VERIFY_EMAIL_EXPIRY - The number of seconds that the email verification link is valid for. If a user does not verify their email address within this time, they will need to sign up again.

Finally, the value for TEAM_CREATION controls who can create new teams. It can be set to one of the following values: Possible values: "CB_MEMBERS", "CB_ADMINS", "CB_NOBODY".

Maximums

There are a number of maximums that can be set, to prevent (accidental) abuse of the system. The defaults are set to values that should be reasonable for most installations, but you may want to adjust them to your specific needs. In particular: because you are self-hosting, you may want to be more generous with the limits than would be available in the hosted versions of our competitors.

  • MAX_EVENT_SIZE: Maximum size of an event that Bugsink can process. Default: 1 MB.

  • MAX_ENVELOPE_SIZE: Maximum size of an envelope that Bugsink can process. Default: 100 MB.

  • MAX_ENVELOPE_COMPRESSED_SIZE: Maximum size of a compressed envelope that Bugsink can process. Default: 20 MB.

  • MAX_EVENTS_PER_PROJECT_PER_5_MINUTES: Maximum number of events a project can generate in 5 minutes. Default: 1,000.

  • MAX_EVENTS_PER_PROJECT_PER_HOUR: Maximum number of events a project can generate in an hour. Default: 5,000.

Display settings

The following (as it stands, short) list of settings is used to customize the appearance and behavior of Bugsink.

  • TIME_ZONE: Default time zone for displaying dates and times. Default: "UTC". Example: "America/New_York".

Background work

Bugsink can offload “things that take relatively long” to a background worker. In particular: the processing of events and the sending of emails.

Doing so increases the stability of the webserver, but it comes with the additional complexity of running a separate worker process.

The templates that come with the installation guides pick default settings that make sense for each of their respective goals. That is: for local development everything is just done right in the request/response loop, and for production installs the separate worker process is configured and started.

  • DIGEST_IMMEDIATELY: Actual processing of events is called “digesting”; this is to distinguish it from “ingesting” which is the simple act of receiving them from the SDKs. If this variable is set to False, digesting happens in the background process. If it’s True, it happens in the request/response loop. Note that if you set this to False, you will probably also want to set TASK_ALWAYS_EAGER to False to actually offload the process of digestion to snappea.

  • TASK_ALWAYS_EAGER: Setting this to True tells snappea to not actually postpone the tasks, but to do them inline. Remember to actually start snappea if you switch to TASK_ALWAYS_EAGER=False (and vice versa).

  • NUM_WORKERS: number of worker threads in the snappea worker process. Note that the most time-consuming work that the snappea worker does (event-processing) happens serially, so adding more workers will not make that faster. Pick something in the range of 2-4. (In the docker setup this variable is called SNAPPEA_NUM_WORKERS)

  • PID_FILE: pid-file location of the snappea worker

  • WAKEUP_CALLS_DIR: directory that is used by snappea to wake up the worker without relying on a busy-loop.

More about the design of our background worker called Snappea.

Docker-specific settings

Some variables are used exclusively in the Docker setup (and are not used in the bugsink_conf.py file).

  • PORT: Port that the webserver listens on. Default: 8000. This makes sure that the webserver listens on this port. You’ll need to do some version of EXPOSE yourself (e.g. add -p PORT:PORT to your docker run command).

  • CREATE_SUPERUSER: a value username:password, that will be used to create a superuser when the container starts. The superuser is created only if it doesn’t already exist.

Miscellaneous

  • SECRET_KEY: Secret key for cryptographic signing in Django. It must be a random string, at least 50 characters long. You can generate one using e.g. openssl rand -base64 50, or use "rjjszIRqlQ0BHXCIUnwVrsmW6Ud7ipBVQ3j5IpY90l4MIZQLRE".

  • DEBUG: Enables or disables debug mode. Default: False. Use this is you want to debug Bugsink itself (you probably don’t). Setting this to True requires you to separately run pip install django-debug-toolbar.

  • DEBUG_CSRF: Enables or disables CSRF debugging. Defaults to "USE_DEBUG", which tells Bugsink to turn on CSRF debugging when DEBUG is True.

  • VALIDATE_ON_DIGEST: controls validation of incoming events. When this is “none” (the default) there is no validation. Other values are “warn” and “strict”. When set to "warn", Bugsink will print a warning to the logs and attempt to process the event. When set to "strict", Bugsink will refuse to further process the event.

  • KEEP_ENVELOPES: (an integer, denoting how many envelopes should be stored in the database). Useful for debugging

Next steps

After you’ve configured your settings, you can start using Bugsink. You can either jump into the quickstart or set up projects and teams to start organizing your issues.