diff --git a/SSL.md b/SSL.md new file mode 100644 index 0000000..b8424bf --- /dev/null +++ b/SSL.md @@ -0,0 +1,148 @@ +Statping currently does not serve HTTPS with a SSL certificate as of today. I recommend using NGINX or Apache to serve the SSL and then have the webserver direct traffic to the Statping instance. This guide will show you how to implement SSL onto your Statping server with multiple options. + +**Choose the environment running the Statping instance.** +- [Docker](#docker) +- [NGINX](#nginx) +- [Apache](#apache) + +## Docker +Docker might be the easiest way to get up and running with a SSL certificate. Below is a `docker-compose.yml` file that will run NGINX, LetEncrypt, and Statping. + +1. Point your domain or subdomain to the IP address of the Docker server. This would be done on CloudFlare, Route53, or some other DNS provider. + +2. Replace the `docker-compose.yml` contents: +- `MY.DOMAIN.COM` with the domain you want to use +- `MY@EMAIL.COM` with your email address + +3. Run the docker container by running command `docker-compose up -d`. Give a little bit of time for LetEncrypt to automatically generate your SSL certificate. + +###### `docker-compose.yml` +```yaml +version: '2.3' +services: + nginx: + container_name: nginx + image: jwilder/nginx-proxy + ports: + - 0.0.0.0:80:80 + - 0.0.0.0:443:443 + labels: + - "com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxy" + networks: + - internet + restart: always + volumes: + - /var/run/docker.sock:/tmp/docker.sock:ro + - ./statping/nginx/certs:/etc/nginx/certs:ro + - ./statping/nginx/vhost:/etc/nginx/vhost.d + - ./statping/nginx/html:/usr/share/nginx/html:ro + - ./statping/nginx/dhparam:/etc/nginx/dhparam + environment: + DEFAULT_HOST: MY.DOMAIN.COM + + letsencrypt: + container_name: letsencrypt + image: jrcs/letsencrypt-nginx-proxy-companion + networks: + - internet + restart: always + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - ./statping/nginx/certs:/etc/nginx/certs + - ./statping/nginx/vhost:/etc/nginx/vhost.d + - ./statping/nginx/html:/usr/share/nginx/html + - ./statping/nginx/dhparam:/etc/nginx/dhparam + + statping: + container_name: statping + image: hunterlong/statping:latest + restart: always + networks: + - internet + depends_on: + - nginx + volumes: + - ./statping/app:/app + environment: + VIRTUAL_HOST: MY.DOMAIN.COM + VIRTUAL_PORT: 8080 + LETSENCRYPT_HOST: MY.DOMAIN.COM + LETSENCRYPT_EMAIL: MY@EMAIL.COM + +networks: + internet: + driver: bridge +``` + +## NGINX +If you already have a NGINX web server running, you just have to add a proxy pass and your SSL certs to the nginx config or as a vhost. By default Statping runs on port 8080, you can change this port by starting server with `statping -ip 127.0.0.1 -port 9595`. + +- Replace `/my/absolute/directory/for/cert/server.crt` with SSL certificate file. +- Replace `/my/absolute/directory/for/key/server.key` with SSL key file. +- Run `service nginx restart` and try out https on your domain. + +##### Tutorials +- [NGINX Guide](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) +- [How To Set Up Nginx Load Balancing with SSL Termination](https://www.digitalocean.com/community/tutorials/how-to-set-up-nginx-load-balancing-with-ssl-termination) + +###### `/etc/nginx/nginx.conf` +``` +#user nobody; +worker_processes 1; +events { + worker_connections 1024; +} +http { + include mime.types; + default_type application/octet-stream; + send_timeout 1800; + sendfile on; + keepalive_timeout 6500; + server { + listen 80; + server_name localhost; + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Client-Verify SUCCESS; + proxy_set_header X-Client-DN $ssl_client_s_dn; + proxy_set_header X-SSL-Subject $ssl_client_s_dn; + proxy_set_header X-SSL-Issuer $ssl_client_i_dn; + proxy_read_timeout 1800; + proxy_connect_timeout 1800; + } + } + # HTTPS server + + server { + listen 443; + server_name localhost; + + ssl on; + ssl_certificate /my/absolute/directory/for/cert/server.crt; + ssl_certificate_key /my/absolute/directory/for/key/server.key; + ssl_session_timeout 5m; + + ssl_protocols SSLv2 SSLv3 TLSv1; + ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; + ssl_prefer_server_ciphers on; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Client-Verify SUCCESS; + proxy_set_header X-Client-DN $ssl_client_s_dn; + proxy_set_header X-SSL-Subject $ssl_client_s_dn; + proxy_set_header X-SSL-Issuer $ssl_client_i_dn; + proxy_read_timeout 1800; + proxy_connect_timeout 1800; + } + } +} +``` + +## Apache \ No newline at end of file