BlogDocumentationDocsRegister

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.

  • 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).

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, secretKey, and possibly image.tag.
  3. Install the chart helm install glitchtip/glitchtip --set databaseURL=your_db --set secretKey=random_string (you may want to use a values.yaml file instead of --set)

Our chart is published here. We only publish chart updates when the helm configuration changes. For regular GlitchTip updates, set the image.tag value to the version you want on dockerhub. Leaving the tag as "latest" is not recommended for production use cases as you may get "surprise" updates.

For high availability, production servers we recommend using multiple Kubernetes Nodes, an ingress and/or load balancer, a pod disruption budget, anti-affinity, and a managed Postgresql high availability database.

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_URL Set redis host explicitly. Example: redis://:password@host:port/database. You may also set them separately with REDIS_HOST, REDIS_PORT, REDIS_DATABASE, and REDIS_PASSWORD.
  • 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 separated values and single quotes on certain values such as 'self'.
  • ENABLE_OPEN_USER_REGISTRATION (Default False) Set to True to allow any user to register. When False, user self sign up is disabled after the first organization is created. This setting may be useful for SaaS services or self hosting that encourage peers to sign themselves up.

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.