Docker configuration to quickly setup your own Canarytokens.
Switch branches/tags
Nothing to show
Clone or download
thinkst Update the max allowed request size of Nginx
Summary: The maximum request entity size of Nginx had to be increased to a value greater than the maximum file upload size in the frontend, to allow for error handling and user feedback.

Test Plan: Tested on localhost.

Reviewers: #devs, nick

Reviewed By: #devs, nick

Maniphest Tasks: T821

Differential Revision:
Latest commit ce25eb3 Aug 16, 2018

Dockerized Canarytokens

by Thinkst Applied Research


Canarytokens helps track activity and actions on your network.


  • At least one domain name. If you want to enable PDF-opening tracking, at least two domains.
  • Internet-facing Docker host. You can install Docker on a Linux host quickly.

Setup (in Ubuntu)

  • Boot your Docker host, and take note of the public IP.
  • Configure your domains so that their nameservers point to the public IP of the Docker host. This requires a change at your Registrar. Simply changing NS records in the zonefile is insufficient.
  • Clone the Docker setup:
$ git clone
$ cd canarytokens-docker
  • Install Docker compose (if not already present):
$ sudo apt-get install python-pip python-dev
$ sudo pip install -U docker-compose
#if this breaks with PyYAML errors, install the libyaml development package
# sudo apt-get install libyaml-dev
  • Configuration is held in the two .env files. Edit these. Uncomment 'CANARY_PUBLIC_DOMAIN' in switchboard.ev and set it to one of the domains defined for 'CANARY_DOMAIN' in frontend.ev(if you do not uncomment and set it, the Public IP will be used). If you are using Mailgun to send emails, uncomment 'CANARY_MAILGUN_DOMAIN_NAME' and 'CANARY_MAILGUN_API_KEY' from switchboard.ev and set the values. If you are using Mandrill or Sendgrid instead, uncomment the appropriate API key setting and set it. Here's example files for a setup that generates tokens on, and (PDFs), running on a host with public domain 'my.domain' and IP, using Mailgun Domain Name 'x.y' and API Key 'zzzzzzzzzz':
    • frontend.ev
#These domains are used for general purpose tokens,

#These domains are only used for PDF tokens

#Requires a Google API key to generate incident map

  • switchboard.ev (Example using Mailgun for email)
  • Finally, download and initiate the images:
$ docker-compose up

Persisting data

The tokens are saved in a Redis database file which exists outside of the Docker containers. Look for dump.rdb in the canarytokens-docker/data directory.

If you want to wipe all your tokens, delete dump.rdb.

Its 2018: I want HTTPS!

We have a separate docker compose file which will automate (mostly) getting you up and running a Canarytokens server with HTTPS. You will need to do the following:

  • Edit the certbot.env. You will need to provide your domain and email address (these are necessary for the certbot's registration process). E.g.
  • Now when you want to bring up your server, you will use docker-compose -f docker-compose-letsencrypt.yml up which will run the server in the foreground so you can make sure everything gets started alright.

  • If everything is running, you may want to CTRL+C, run docker-compose -f docker-compose-letsencrypt.yml down to get to a clean slate and then rerun docker-compose -f docker-compose-letsencrypt.yml up -d with the added -d to run the server in the background (in daemon mode)

  • Please keep in mind that using the HTTPS method will use the email you specified and the domain name to register the certificate. You can read about the lets encrypt process (using cerbot) over here. The process involves verifying that you are the owner of the domain you have specified and registering you with lets encrypt.

  • THERE IS A RATE LIMIT. So don't keep bringing this server up and down otherwise you will quickly hit a lets encrypt certificate generation limit. To avoid this, for testing purposes you may add --staging to the ./certbot-auto command in cerbot-nginx/ which will test whether lets encrypt gives you the certificate.