GlitchTip Installation Guide

GlitchTip can be run with Docker. We recommend Docker Compose or Heroku for smaller installations.

Docker Compose

Docker Compose is a simple way to run GlitchTip on a single server.

1. Install Docker and Docker Compose. On Debian/Ubuntu this is sudo apt install docker-compose docker.io
2. Copy docker-compose.sample.yml to your server as docker-compose.yml.
3. Edit the environment section of docker-compose.yml. See the Configuration section below.
4. Start docker service docker-compose up -d now the service should be running on port 8000.

It's highly recommended to configure SSL next. Use nginx or preferred solution.

Recommended nginx and SSL solution

• Install nginx. Ex: sudo apt install nginx.
• (on Debian/Ubuntu) edit /etc/nginx/sites-enabled/default for example:

server {
    server_name glitchtip.example.com;
    access_log  /var/log/nginx/access.log;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

This configuration will direct glitchtip.example.com to port 8000 (the default GlitchTip docker compose port).

• Install and run certbot. Follow instructions.

Upgrading

1. Pull latest docker image docker-compose pull
2. Restart docker-compose stop and docker-compose up -d

Database migrations will automatically happen.

Heroku

Heroku is a simple environment suitable for deployments small to large.

1. Create Heroku app: heroku apps:create <heroku-app-name>
2. Create Postgres database heroku addons:create heroku-postgresql --app <heroku-app-name>
3. Set SECRET_KEY and other environment variables heroku config:set SECRET_KEY=random_string -a glitchtip. See Configuration.
4. Deploy Docker image
   • docker pull glitchtip/glitchtip
   • docker tag glitchtip/glitchtip registry.heroku.com/<heroku-app-name>/web
   • heroku container:login
   • docker push registry.heroku.com/<heroku-app-name>/web
   • heroku container:release web

For production environments, you will likely wish to deploy a worker dyno. This requires at least hobby tier dynos. This is necessary for notifications and more.

1. Create Redis instance: heroku addons:create heroku-redis:hobby-dev
2. docker tag glitchtip/glitchtip registry.heroku.com/<heroku-app-name>/worker
3. docker push registry.heroku.com/<heroku-app-name>/worker
4. heroku container:release worker

GlitchTip will detect being run as a worker dyno and automatically start a celery worker with integrated beat scheduler.

For very high traffic sites, you may wish to run multiple workers. Limit the beat servers to just 1. Create another Heroku role and set the environment variable SERVER_ROLE=worker.

Upgrading

1. docker pull glitchtip/glitchtip
2. docker tag glitchtip/glitchtip registry.heroku.com/<heroku-app-name>/web
3. docker push registry.heroku.com/<heroku-app-name>/web
4. heroku container:release web

If using a worker, run the same commands with worker instead of web.

Helm

Installing GlitchTip with Helm for Kubernetes is a good option for high throughput sites and users who are very comfortable using Kubernetes. This method is recommended only for users who are very comfortable managing Docker and Kubernetes.

app.glitchtip.com uses this method with a managed DigitalOcean database.

1. Add our Helm chart repo helm repo add glitchtip https://glitchtip.gitlab.io/glitchtip-helm-chart/
2. Review our values.yaml. At a minimum you'll need to set databaseURL and secretKey.
3. Install the chart helm install glitchtip/glitchtip --set databaseURL=your_db --set secretKey=random_string

Our chart is published here.

Configuration

Required environment variables:

• SECRET_KEY set to any random string
• Set up email:
  • EMAIL_URL: SMTP string. It will look something like "smtp://email@:password@smtp_url:port". See format examples here
  • Alternatively, use the Mailgun API by setting MAILGUN_API_KEY and MAILGUN_SENDER_DOMAIN. Set EMAIL_BACKEND to anymail.backends.mailgun.EmailBackend
• DEFAULT_FROM_EMAIL Default from email address. Example info@example.com
• GLITCHTIP_DOMAIN Set to your domain. Example: https://glitchtip.example.com

Optional environment variables:

• GLITCHTIP_MAX_EVENT_LIFE_DAYS (Default 90) Events and associated data older than this will be deleted from the database
• REDIS_HOST Set redis host explicitely.
• DATABASE_URL Set postgres connect string.
• Content Security Policy (CSP) headers are enabled by default. In most cases there is no need to change these. However you may add environment variables as documented in django-csp to modify them. For example, set CSP_DEFAULT_SRC='self',scripts.example.com to modify the default CSP header. Note the usage of comma seperated values and single quotes on certain values such as 'self'.

Django Admin

Django Admin is not necessary for most users. However if you'd like the ability to fully manage users beyond what our frontend offers, it may be useful. To enable, create a super user via the Django command

./manage.py createsuperuser

Then go to /admin/ and log in.

Social Authentication (OAuth)

You may add Social Accounts in Django Admin at /admin/socialaccount/socialapp/. GlitchTip supports Gitlab, Google, Microsoft, and Github OAuth. If you are not familiar with OAuth, please refer to django-allauth's providers documentation.