From 9fe79c9f234bb6982ba5dd8e36715563d01185df Mon Sep 17 00:00:00 2001 From: "R. Miles McCain" Date: Sun, 3 May 2020 10:39:13 -0400 Subject: [PATCH] Add troubleshooting guide --- GUIDE.md | 25 +++++++++++++++++++++++-- README.md | 6 +++++- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/GUIDE.md b/GUIDE.md index 5d52e6a..9831a46 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,4 +1,4 @@ -# Getting Started +# Usage Guide ## Table of Contents @@ -9,6 +9,7 @@ * [Configuring a Reverse Proxy](#configuring-a-reverse-proxy) + [Cloudflare](#cloudflare) + [Nginx](#nginx) ++ [Troubleshooting](#troubleshooting) --- @@ -38,7 +39,7 @@ Before continuing, please be sure to have the latest version of Docker installed ## Updating Your Configuration -When you first setup Shynet, you set a number of environment variables that determine first-run initialization settings (these variables start with `SHYNET_`). Once they're first set, though, changing them won't have any effect. Here's how to update their values: +When you first setup Shynet, you set a number of environment variables that determine first-run initialization settings (these variables start with `SHYNET_`). Once they're first set, though, changing them won't have any effect. Be sure to run the following commands in the same way that you deploy Shynet (i.e., linked to the same database). * Create an admin account by running `docker run --env-file= milesmcc/shynet:latest python manage.py registeradmin `. The command will print a temporary password that you'll be able to use to log in. @@ -164,3 +165,23 @@ Nginx is a self hosted, highly configurable webserver. Nginx can be configured t * [How to add SSL/HTTPS to Nginx (Ubuntu 18.04)](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04) * [How to add SSL/HTTPS to Nginx (Ubuntu 16.04)](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-16-04) * [Nginx Documentation](https://nginx.org/en/docs/) + +--- + +## Troubleshooting + +Here are solutions for some common issues. If your situation isn't described here or the solution didn't work, feel free to [create an issue](https://github.com/milesmcc/shynet/issues/new) (but be sure to check for duplicate issues first). + +#### The admin panel works, but no page views are showing up! + +* If you are running a single Shynet webserver instance (i.e., you followed the default installation instructions), verify that you haven't set `CELERY_TASK_ALWAYS_EAGER` to `False` in your environment file. +* Verify that your cache is properly configured. In single-instance deployments, this means making sure that you haven't set any `REDIS_*` or `CELERY_*` environment variables (those are for more advanced deployments; you'll just want the defaults). +* If your service is configured to respect Do Not Track (under "Advanced Settings"), verify that your browser isn't sending the `DNT=1` header with your requests (or temporarily disable DNT support in Shynet while testing). Sometimes, an adblocker or privacy browser extension will add this header to requests unexpectedly. + +#### Shynet isn't linking different pageviews from the same visitor into a single session! + +* Verify that your cache is properly configured. (See #2 above.) In multi-instance deployments, it's critical that all webservers are using the _same_ cache—so make sure you configure a Redis cache if you're using a non-default installation. + +#### I changed the `SHYNET_WHITELABEL`/`SHYNET_HOST` environment variable, but nothing happened! + +* Those values only affect how your Shynet instance is setup on first run; once it's configured, they have no effect. See [updating your configuration](#updating-your-configuration) for help on how to update your configuration. diff --git a/README.md b/README.md index 578576f..42d9094 100644 --- a/README.md +++ b/README.md @@ -93,7 +93,7 @@ Shynet is pretty simple, but there are a few key terms you need to know in order ## Installation -You can find installation instructions in the [Getting Started Guide](GUIDE.md#installation). Out of the box, we support deploying via a simple +You can find intructions on getting started and usage in the [Usage Guide](GUIDE.md#installation). Out of the box, we support deploying via a simple Docker container, docker-compose, or Kubernetes (see [kubernetes](/kubernetes)). ## FAQ @@ -102,6 +102,10 @@ Docker container, docker-compose, or Kubernetes (see [kubernetes](/kubernetes)). **Is this GDPR compliant?** It depends on how you use it. If you're worried about GDPR, you should talk to a lawyer about your particular data collection practices. I'm not a lawyer. (And this isn't legal advice.) +## Troubleshooting + +Having trouble with Shynet? Check out the [troubleshooting guide](GUIDE.md#troubleshooting), or [create an issue](https://github.com/milesmcc/shynet/issues/new) if you think you found a bug in Shynet itself (or have a feature suggestion). + ## Roadmap To see the upcoming planned features, check out the repository's [roadmap project](https://github.com/milesmcc/shynet/projects/1). Upcoming features include data aggregation through rollups, anomaly detection, detailed data exports, two-factor authentication, and a data deletion tool.