Update and expand the GUIDE (merges #3)

2020-05-02 11:00:40 -04:00 · 2020-05-02 11:00:40 -04:00 · 34e698e309
commit 34e698e309
parent f33e0e342c
7 changed files with 43 additions and 198 deletions
--- a/GUIDE.md
+++ b/GUIDE.md
@ -2,17 +2,13 @@
 ## Table of Contents
-* [Installation](#installation)
+- [Installation](#installation)
-  * [Basic Installation](#basic-installation)
+- [Updating Your Configuration](#updating-your-configuration)
 - [Enhancements](#enhancements)
  * [Installation with SSL](#installation-with-ssl)
-* [How to Use](#how-to-use)
+  * [Configuring a Reverse Proxy](#configuring-a-reverse-proxy)
-  * [Basic Usage](#basic-usage)
+    + [Cloudflare](#cloudflare)
-    * [Add your first website](#add-your-first-website)
+    + [Nginx](#nginx)
  * [Advanced Usage](#advanced-usage)
 * [Enhancements](#enhancements)
  * [Setting up a reverse proxy](#configuring-a-reverse-proxy)
    * [Cloudflare](#cloudflare)
    * [Nginx](#nginx)
 ---
@ -30,79 +26,38 @@ Before continuing, please be sure to have the latest version of Docker installed
 2. Have a PostgreSQL server ready to go. This can be on the same machine as the deployment, or elsewhere. You'll just need a username, password, host, and port. (For info on how to setup a PostgreSQL server on Ubuntu, follow [this guide](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-18-04)).
-3. Configure an environment file for Shynet. (For example, create a file called `.env`.) Be sure to swap out the variables below with the correct values for your setup. (The comments refer to the lines that follow. Note that Docker is weird with quotes, so it tends to be better to omit them from your env file.)
+3. Configure an environment file for Shynet, using [this file](/TEMPLATE.env) as a template. (This file is typically named `.env`.) Make sure you set the database settings, or Shynet won't be able to run.
-```properties
+4. Launch the Shynet server by running `docker run --env-file=<your env file> milesmcc/shynet:latest`. Watch the output of the script; if it's the first run, you'll see a temporary password printed that you can use to log in. You may need to bind Docker's port 8080 (where Shynet runs) to your local port 80 (http); this can be done using the flag `-p 80:8080` after `run`.
 # Database
 DB_NAME=<your db name>
 DB_USER=<your db user>
 DB_PASSWORD=<your db user password>
 DB_HOST=<your db host>
 DB_PORT=<your db port; use 5432 if you don't know>
-# General Django settings
+5. Visit your service's homepage, and verify everything looks right! You should see a login prompt. Log in with the credentials from step 4. You'll probably be prompted to "confirm your email"—if you haven't set up an email server, the confirmation email will be printed to the console instead.
 DJANGO_SECRET_KEY=<your Django secret key; just a random string>
 # Don't leak error details to visitors, very important
 DEBUG=False
 # Unless you are using an external Celery task queue, make sure this
 # is set to True.
 CELERY_TASK_ALWAYS_EAGER=True 
 # For better security, set this to your deployment's domain. Comma separated.
 ALLOWED_HOSTS=*
 # Set to True (capitalized) if you want people to be able to sign up for your Shynet instance (not recommended)
 SIGNUPS_ENABLED=False
 # Change as required
 TIME_ZONE=America/New_York
 # Set to "False" if you will not be serving content over HTTPS
 SCRIPT_USE_HTTPS=True
 ```
-For more advanced deployments, you may consider adding the following settings to your environment file. **The following settings are optional, and not required for simple deployments.**
+6. Create a service by clicking "+ Create Service" in the top right hand corner. Fill out the options as appropriate. Once you're done, press "create" and you'll be redirected to your new service's analytics page.
-```properties
+7. Finally, click on "Manage" in the top right of the service's page to get the tracking script code. Inject this script on all pages you'd like the service to track.
 # Email settings
 EMAIL_HOST_USER=<your SMTP email user>
 EMAIL_HOST_PASSWORD=<your SMTP email password>
 EMAIL_HOST=<your SMTP email hostname>
 SERVER_EMAIL=Shynet <noreply@shynet.example.com>
-# Redis and queue settings; not necessary for single-instance deployments
+## Updating Your Configuration
 REDIS_CACHE_LOCATION=redis://redis.default.svc.cluster.local/0 
 # If set, make sure CELERY_TASK_ALWAYS_EAGER is False
 CELERY_BROKER_URL=redis://redis.default.svc.cluster.local/1
-# Other Shynet settings 
+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:
 # How frequently should the monitoring script "phone home" (in ms)?
 SCRIPT_HEARTBEAT_FREQUENCY=5000
 # Should only superusers (admins) be able to create services? This is helpful
 # when you'd like to invite others to your Shynet instance but don't want
 # them to be able to create services of their own.
 ONLY_SUPERUSERS_CREATE=False
 ```
-4. Setup the Shynet database by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py migrate`.
+* Create an admin account by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py registeradmin <your email>`. The command will print a temporary password that you'll be able to use to log in.
-5. Create your admin account by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py registeradmin <your email>`. The command will print a temporary password that you'll be able to use to log in.
+* Configure Shynet's hostname (e.g. `shynet.example.com` or `localhost:8000`) by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py hostname "<your hostname>"`. This doesn't affect Shynet's bind port; instead, it determines what hostname to inject into the tracking script. (So you'll want to use the "user-facing" hostname here.)
-6. Configure Shynet's hostname (e.g. `shynet.example.com` or `localhost:8000`) by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py hostname "<your hostname>"`. This doesn't affect Shynet's bind port; instead, it determines what hostname to inject into the tracking script. (So you'll want to use the "user-facing" hostname here.)
+* Name your Shynet instance by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py whitelabel "<your instance name>"`. This could be something like "My Shynet Server" or "Acme Analytics"—whatever suits you.
-7. Name your Shynet instance by running `docker run --env-file=<your env file> milesmcc/shynet:latest python manage.py whitelabel "<your instance name>"`. This could be something like "My Shynet Server" or "Acme Analytics"—whatever suits you.
+---
-8. Launch the Shynet server by running `docker run --env-file=<your env file> milesmcc/shynet:latest`. You may need to bind Docker's port 8080 (where Shynet runs) to your local port 80 (http); this can be done using the flag `-p 80:8080` after `run`.
+## Enhancements
 9. Visit your service's homepage, and verify everything looks right! You should see a login prompt. Log in with the credentials from step 5. You'll probably be prompted to "confirm your email"—if you haven't set up an email server, the confirmation email will be printed to the console instead.
 10. Create a service by clicking "+ Create Service" in the top right hand corner. Fill out the options as appropriate. Once you're done, press "create" and you'll be redirected to your new service's analytics page.
 11. Finally, click on "Manage" in the top right of the service's page to get the tracking script code. Inject this script on all pages you'd like the service to track.
 ### Installation with SSL
-If you are going to be running Shynet through a reverse proxy, please use the [Basic Installation](#basic-installation) guide instead.
+If you are going to be running Shynet through a reverse proxy, please see [Configuring a Reverse Proxy](#configuring-a-reverse-proxy) instead.
 0. We'll be cloning this into the home directory to make this installation easier, so run `cd ~/` if you need to.
-1. Instead of pulling from Docker, we will be pulling from GitHub and building in Docker so that we may easily add SSL certificates. You will want to run `git clone https://github.com/milesmcc/shynet.git` to clone the GitHub repo to your computer.
+1. Instead of pulling from Docker, we will be pulling from GitHub and building using Docker in order to easily add SSL certificates. You will want to run `git clone https://github.com/milesmcc/shynet.git` to clone the GitHub repo to your current working directory.
 2. To install `certbot` follow [the guide here](https://certbot.eff.org/instructions) or follow along below
   * Ubuntu 18.04
@ -114,7 +69,7 @@ If you are going to be running Shynet through a reverse proxy, please use the [B
     * `sudo apt-get install certbot`
 3. Run `sudo certbot certonly --standalone` and follow the instructions to generate your SSL certificate.
-   * If you registering it to a domain name like `example.com`, please be sure to point your DNS records to your server before running `certbot`.
+   * If you registering the certificate to a domain name like `example.com`, please be sure to point your DNS records to your current server before running `certbot`.
 4. We are going to move the SSL certificates to the Shynet repo with with command below. Replace `<domain>` with the domain name you used in step 3.
   * `cp /etc/letsencrypt/live/<domain>/{cert,privkey}.pem ~/shynet/shynet/`
@ -124,131 +79,25 @@ If you are going to be running Shynet through a reverse proxy, please use the [B
   * `mv ~/shynet/shynet/ssl.webserver.sh ~/shynet/shynet/webserver.sh`
 6. Now we build the image!
-   * `docker image build shynet -t milesmcc/shynet:latest-ssl`
+   * `docker image build shynet -t shynet-ssl:latest`
 7. Have a PostgreSQL server ready to go. This can be on the same machine as the deployment, or elsewhere. You'll just need a username, password, host, and port (default is `5432`). (For info on how to setup a PostgreSQL server on Ubuntu, follow [this guide](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-18-04)).
-8. Configure an environment file for Shynet. (For example, create a file called `.env`.) Be sure to swap out the variables below with the correct values for your setup. (The comments refer to the lines that follow. Note that Docker is weird with quotes, so it tends to be better to omit them from your env file.)
+8. Follow the [Basic Installation](#basic-installation) guide with just one modification: in step #4, change the local bind port from `80` to `443`, and use `shynet-ssl:latest` as your Docker image instead of `milesmcc/shynet:latest`.
 ```properties
 # Database
 DB_NAME=<your db name>
 DB_USER=<your db user>
 DB_PASSWORD=<your db user password>
 DB_HOST=<your db host>
 DB_PORT=<your db port>
 # General Django settings
 DJANGO_SECRET_KEY=<your Django secret key; just a random string>
 # Don't leak error details to visitors, very important
 DEBUG=False
 # Unless you are using an external Celery task queue, make sure this
 # is set to True.
 CELERY_TASK_ALWAYS_EAGER=True 
 # For better security, set this to your deployment's domain. Comma separated.
 ALLOWED_HOSTS=*
 # Set to True (capitalized) if you want people to be able to sign up for your Shynet instance (not recommended)
 SIGNUPS_ENABLED=False
 # Change as required
 TIME_ZONE=America/New_York
 # Set to "False" if you will not be serving content over HTTPS
 SCRIPT_USE_HTTPS=True
 ```
 For more advanced deployments, you may consider adding the following settings to your environment file. **The following settings are optional, and not required for simple deployments.**
 ```properties
 # Email settings
 EMAIL_HOST_USER=<your SMTP email user>
 EMAIL_HOST_PASSWORD=<your SMTP email password>
 EMAIL_HOST=<your SMTP email hostname>
 SERVER_EMAIL=Shynet <noreply@shynet.example.com>
 # Redis and queue settings; not necessary for single-instance deployments
 REDIS_CACHE_LOCATION=redis://redis.default.svc.cluster.local/0 
 # If set, make sure CELERY_TASK_ALWAYS_EAGER is False
 CELERY_BROKER_URL=redis://redis.default.svc.cluster.local/1
 # Other Shynet settings 
 # How frequently should the monitoring script "phone home" (in ms)?
 SCRIPT_HEARTBEAT_FREQUENCY=5000
 # Should only superusers (admins) be able to create services? This is helpful
 # when you'd like to invite others to your Shynet instance but don't want
 # them to be able to create services of their own.
 ONLY_SUPERUSERS_CREATE=False
 ```
 9. Setup the Shynet database by running `docker run --env-file=<your env file> milesmcc/shynet:latest-ssl python manage.py migrate`.
 10. Create your admin account by running `docker run --env-file=<your env file> milesmcc/shynet:latest-ssl python manage.py registeradmin <your email>`. The command will print a temporary password that you'll be able to use to log in.
 11. Configure Shynet's hostname (e.g. `shynet.example.com` or `localhost:8000`) by running `docker run --env-file=<your env file> milesmcc/shynet:latest-ssl python manage.py hostname "<your hostname>"`. This doesn't affect Shynet's bind port; instead, it determines what hostname to inject into the tracking script. (So you'll want to use the "user-facing" hostname here.)
 12. Name your Shynet instance by running `docker run --env-file=<your env file> milesmcc/shynet:latest-ssl python manage.py whitelabel "<your instance name>"`. This could be something like "My Shynet Server" or "Acme Analytics"—whatever suits you.
 13. Launch the Shynet server by running `docker run --env-file=<your env file> milesmcc/shynet:latest-ssl`. You may need to bind Docker's port 8080 (where Shynet runs) to your local port 443 (https); this can be done using the flag `-p 443:8080` after `run`.
 14. Visit your service's homepage using `https://`, and verify everything looks right! You should see a login prompt. Log in with the credentials from step 10. You'll probably be prompted to "confirm your email"—if you haven't set up an email server, the confirmation email will be printed to the console instead.
 15. Create a service by clicking "+ Create Service" in the top right hand corner. Fill out the options as appropriate. Once you're done, press "create" and you'll be redirected to your new service's analytics page.
 16. Finally, click on "Manage" in the top right of the service's page to get the tracking script code. Inject this script on all pages you'd like the service to track.
 ---
 ## How to Use
 ### Basic Usage
 Basic usage will take place on the dashboard of your website after you log in.
 #### Add your first website
 1. At the top right corner, you will find a button that looks like this:
 <img src="images/newservice.png" height="50" alt="New Service">
 2. Once you click on that, fill in the information for the website you are going to track:
 <img src="images/newserviceinput.png" alt="New Service Input">
 3. You'll be taken to the analytics page for your new service:
 <img src="images/exampledashboard.png" alt="Example Dashboard for Analytics">
 4. At the top right corner, you'll find this button:
 <img src="images/newservicemanage.png" alt="New Service Manage">
 5. After clicking that button you'll be shown some code like so:
 <img src="images/newservicecode.png" alt="New Service Code">
 6. Copy and paste that code and put it between the HTML `<head>` tags on the website you are trying to track.
 7. Go to the website you are trying to track
 8. See if your analytics dashboard is showing any new users
 ---
 ## Enhancements
 ### Configuring a Reverse Proxy
-A Reverse Proxy can be used for many things, including: DDoS protection, caching files to reduce server load, routing HTTPS and/or HTTP connections, hosting multiple services on a single server, [and more](https://www.cloudflare.com/learning/cdn/glossary/reverse-proxy/)!
+A reverse proxy has many benefits. It can be used for DDoS protection, caching files to reduce server load, routing HTTPS and/or HTTP connections, hosting multiple services on a single server, [and more](https://www.cloudflare.com/learning/cdn/glossary/reverse-proxy/)!
 #### Cloudflare
-[Cloudflare](https://www.cloudflare.com/) is a great option because it is free, it will automatically make all your connections go through HTTPS, it offers out-of-the-box security features, acts as a DNS, and requires minimal setup.
+[Cloudflare](https://www.cloudflare.com/) is a great reverse proxy option. It's free, automatically configures HTTPs, offers out-of-the-box security features, provides DNS, and requires minimal setup.
-##### Set up
+1. Follow Cloudflare's [getting started guide](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website).
-1. [Cloudflare has a how-to guide here](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website).
+2. After setting up Cloudflare, here are a few things you should consider doing:
 2. After following that, here are a few things you should do:
   * Under the `SSL` Tab > `Overview` > Change your `SSL/TLS Encryption Mode` to `Flexible`
-   * The following will block your admin panel from anyone who isn't on your IP address, though this is optional.
+   * The following will block your admin panel from anyone who isn't on your IP address. This is optional, but great for security.
     * Under the `Firewall` tab > `Overview` > `+ Create Firewall Rule`:
     * Name: `Admin Panel Restriction`
     * Field: `URI Path`
@ -262,13 +111,13 @@ A Reverse Proxy can be used for many things, including: DDoS protection, caching
 #### Nginx
-Nginx is a self hosted, highly configurable webserver. Nginx can be configured to run as a reverse proxy on either the same machine or a remote machine. Since Nginx can be tweaked for just about anything web related, it does have a longer and more rewarding setup.
+Nginx is a self hosted, highly configurable webserver. Nginx can be configured to run as a reverse proxy on either the same machine or a remote machine.
 ##### Set up
 > **These commands assume Ubuntu.** If you're installing Nginx on a different platform, the process will be different.
-0. Before we start, if you have a Docker container running, please close it.
+0. Before starting, shut down your Docker containers (if any are running)
   * Run `docker container ls` to find the container ID
   * Run `docker stop <container id from the last step>`
@ -298,13 +147,13 @@ Nginx is a self hosted, highly configurable webserver. Nginx can be configured t
   * Save and exit the text editor
     * `:wq` for vi
     * `ctrl+x` then `y` for nano
-   * Link Nginx's `sites-enabled` to read the config we just made
+   * Link Nginx's `sites-enabled` to read the new config
     * `sudo ln -s /etc/nginx/sites-available/reverse-proxy.conf /etc/nginx/sites-enabled/reverse-proxy.conf`
   * Make sure the config is working
     * `service nginx configtest`
     * `service nginx restart`
-4. Restart your docker image, but this time use `8080` since that is what Nginx is now looking for
+4. Restart your Docker image, but this time use `8080` as the local bind port, as that's where we configured Nginx to look
   * `cd ~/`
   * `docker run -p 8080:8080 --env-file=<your env file> milesmcc/shynet:latest`
@ -315,7 +164,3 @@ 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/)
 ---
 **Next steps:** while out of the scope of this short guide, next steps include making Shynet run in the background and integrating it on your sites. Integration instructions are available on each service's management page.
--- a/TEMPLATE.env
+++ b/TEMPLATE.env
@ -2,12 +2,6 @@
 # set to configure Shynet, as well as information about their
 # effects. Make a copy of this file to configure your deployment.
 # Whether to perform checks and setup at startup. For most setups,
 # the recommended value is True.
 PERFORM_CHECKS_AND_SETUP=True
 # Database settings (PostgreSQL)
 DB_NAME=shynet_db
 DB_USER=shynet_db_user
@ -44,10 +38,10 @@ SCRIPT_HEARTBEAT_FREQUENCY=5000
 # them to be able to create services of their own.
 ONLY_SUPERUSERS_CREATE=True
-# If PERFORM_CHECKS_AND_SETUP is True, the following values will be set on
+# Whether to perform checks and setup at startup. For most setups,
-# first run. After they are set once, they won't have any effect.
+# the recommended value is True.
-# (Changing these values WILL NOT affect your Shynet instance.)
+PERFORM_CHECKS_AND_SETUP=True
-# 
+
 # Your admin user's email. A temporary password will be printed
 # to the console on first run.
 SHYNET_ADMIN_EMAIL=you@example.com
@ -56,4 +50,10 @@ SHYNET_ADMIN_EMAIL=you@example.com
 SHYNET_HOST=shynet.example.com
 # What you'd like to call your Shynet instance.
-SHYNET_WHITELABEL=My Shynet Instance
+SHYNET_WHITELABEL=My Shynet Instance
 # Redis and queue settings; not necessary for single-instance deployments.
 # Don't uncomment these unless you know what you are doing!
 # REDIS_CACHE_LOCATION=redis://redis.default.svc.cluster.local/0 
 # If CELERY_BROKER_URL is set, make sure CELERY_TASK_ALWAYS_EAGER is False
 # CELERY_BROKER_URL=redis://redis.default.svc.cluster.local/1
--- a/images/exampledashboard.png
+++ b/images/exampledashboard.png
--- a/images/newservice.png
+++ b/images/newservice.png
--- a/images/newservicecode.png
+++ b/images/newservicecode.png
--- a/images/newserviceinput.png
+++ b/images/newserviceinput.png
--- a/images/newservicemanage.png
+++ b/images/newservicemanage.png