diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..b928358 --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,185 @@ +

+

🔭 Shynet 🔭

+ +

+ Web analytics that's self hosted, cookie free, privacy friendly, and useful(?) +
+

+

+ +## Table of Contents + +* [Installation](#installation) + * [Basic Installation](#basic-installation) + * [Installation with SSL](#installation-with-ssl) + + +## Installation + +Installation of Shynet is easy! Follow the [Basic Installation](#basic-installation) guide below if you'd like to run Shynet over HTTP or if you are going to be running it over HTTPS through a reverse proxy. If you'd like to run Shynet over HTTPS without a reverse proxy, skip ahead to [Installation with SSL](#installation-with-ssl) instead. + +> **These commands assume Ubuntu.** If you're installing Shynet on a different platform, the process will be different. + +Before continuing, please be sure to have the latest version of Docker installed. + +### Basic Installation + +1. Pull the latest version of Shynet using `docker pull milesmcc/shynet:latest`. If you don't have Docker installed, [install it](https://docs.docker.com/get-docker/). + +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 (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)). + +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.) + +``` +# Database +DB_NAME= +DB_USER= +DB_PASSWORD= +DB_HOST= +DB_PORT= + +# General Django settings +DJANGO_SECRET_KEY= +# Don't leak error details to visitors, very important +DEBUG=False +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.** + +```env +# Email settings +EMAIL_HOST_USER= +EMAIL_HOST_PASSWORD= +EMAIL_HOST= +SERVER_EMAIL=Shynet + +# 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 +``` + +4. Setup the Shynet database by running `docker run --env-file= milesmcc/shynet:latest python manage.py migrate`. + +5. Create your 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. + +6. Configure Shynet's hostname (e.g. `shynet.example.com` or `localhost:8000`) by running `docker run --env-file= milesmcc/shynet:latest python manage.py 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.) + +7. Name your Shynet instance by running `docker run --env-file= milesmcc/shynet:latest python manage.py whitelabel ""`. 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= 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`. + +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. + +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. + +2. To install `certbot` follow [the guide here](https://certbot.eff.org/instructions) or follow along below + * Ubuntu 18.04 + * `sudo apt-get update` + * `sudo apt-get install software-properties-common` + * `sudo add-apt-repository universe` + * `sudo add-apt-repository ppa:certbot/certbot` + * `sudo apt-get update` + * `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`. + +4. We are going to move the SSL certificates to the Shynet repo with with command below. Replace `` with the domain name you used in step 3. + * `cp /etc/letsencrypt/live//{cert,privkey}.pem ~/shynet/shynet/` + +5. With that, we are going to replace the `webserver.sh` with `ssl.webserver.sh` to enable the use of SSL certificates. The original `webserver.sh` will be backed up to `backup.webserver.sh` + * `mv ~/shynet/shynet/webserver.sh ~/shynet/shynet/backup.webserver.sh` + * `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` + +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.) + +``` +# Database +DB_NAME= +DB_USER= +DB_PASSWORD= +DB_HOST= +DB_PORT= + +# General Django settings +DJANGO_SECRET_KEY= +# Don't leak error details to visitors, very important +DEBUG=False +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.** + +```env +# Email settings +EMAIL_HOST_USER= +EMAIL_HOST_PASSWORD= +EMAIL_HOST= +SERVER_EMAIL=Shynet + +# 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 +``` + +9. Setup the Shynet database by running `docker run --env-file= milesmcc/shynet:latest-ssl python manage.py migrate`. + +10. Create your admin account by running `docker run --env-file= milesmcc/shynet:latest-ssl python manage.py registeradmin `. 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= milesmcc/shynet:latest-ssl python manage.py 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= milesmcc/shynet:latest-ssl python manage.py whitelabel ""`. 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= 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. + +--- + +**Next steps:** while out of the scope of this short guide, next steps include setting up Shynet behind a reverse proxy (be it your own [Nginx server](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) or [Cloudflare](https://cloudflare.com)), making it run in the background, and integrating it on your sites. Integration instructions are available on each service's management page. \ No newline at end of file diff --git a/README.md b/README.md index ff6d5e2..5b5904e 100644 --- a/README.md +++ b/README.md @@ -85,71 +85,7 @@ Shynet is pretty simple, but there are a few key terms you need to know in order ## Installation -To install Shynet using the simplest possible setup, follow these instructions. Instructions for multi-machine deployments will be available soon. - -> **These commands assume Ubuntu.** If you're installing Shynet on a different platform, the process will be different. - -1. Pull the latest version of Shynet using `docker pull milesmcc/shynet:latest`. If you don't have Docker installed, [install it](https://docs.docker.com/get-docker/). - -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, and host. (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.) - -``` -# Database -DB_NAME= -DB_USER= -DB_PASSWORD= -DB_HOST= - -# General Django settings -DJANGO_SECRET_KEY= -# Don't leak error details to visitors, very important -DEBUG=False -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.** - -```env -# Email settings -EMAIL_HOST_USER= -EMAIL_HOST_PASSWORD= -EMAIL_HOST= -SERVER_EMAIL=Shynet - -# 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 -``` - -4. Setup the Shynet database by running `docker run --env-file= milesmcc/shynet:latest python manage.py migrate`. - -5. Create your 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. - -6. Configure Shynet's hostname (e.g. `shynet.example.com` or `localhost:8000`) by running `docker run --env-file= milesmcc/shynet:latest python manage.py 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.) - -7. Name your Shynet instance by running `docker run --env-file= milesmcc/shynet:latest python manage.py whitelabel ""`. 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= milesmcc/shynet:latest`. You may need to bind Docker's port 8000 (where Shynet runs) to your local port 8000; this can be done using the flag `-p 8080:8080`. - -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. - -**Next steps:** while out of the scope of this short guide, next steps include setting up Shynet behind a reverse proxy (be it your own [Nginx server](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) or [Cloudflare](https://cloudflare.com)), making it run in the background, and integrating it on your sites. Integration instructions are available on each service's management page. - +You can find installation instructions in our [Getting Started Guide](GUIDE.md#installation)! ## FAQ diff --git a/shynet/ssl.webserver.sh b/shynet/ssl.webserver.sh new file mode 100644 index 0000000..40047f0 --- /dev/null +++ b/shynet/ssl.webserver.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +# Start Gunicorn processes +echo Launching Shynet web server... +exec gunicorn shynet.wsgi:application \ + --bind 0.0.0.0:8080 \ + --workers 3 \ + --timeout 100 \ + --certfile=cert.pem \ + --keyfile=privkey.pem \ No newline at end of file