Updating documentation

.dockerignore

@@ -1,5 +1,5 @@
-# Examples
+# Docs
-examples/
+README.md
 
 # Git
 .git/

README.md

@@ -0,0 +1,71 @@
+# [<img alt="PrivateBin" src="https://cdn.rawgit.com/PrivateBin/assets/master/images/minified/logo.svg" width="500" />](https://privatebin.info/)
+
+**PrivateBin** is a minimalist, open source online [pastebin](https://en.wikipedia.org/wiki/Pastebin)
+where the server has zero knowledge of pasted data. Data is encrypted and decrypted in the browser
+using 256bit AES in [Galois Counter mode](https://en.wikipedia.org/wiki/Galois/Counter_Mode).
+
+This repository contains the Dockerfile and resources needed to create a docker image with a pre-installed
+PrivateBin instance in a secure default configuration. The images are based on the docker hub php/fpm-alpine
+image, extended with the GD module required to generate comment avatars and the Nginx webserver to serve
+static JavaScript libraries, CSS & logos. All logs of php-fpm and Nginx (access & errors) are forwarded to
+docker.
+
+## Running the image
+
+Assuming you have docker successfully installed and internet access, you can fetch and run the image from
+the docker hub like this:
+
+```bash
+docker run -d --restart="always" --read-only -p 8080:80 -v privatebin-data:/srv/data privatebin/nginx-fpm-alpine:1.1.1
+```
+
+The parameters explained, in order of importance:
+
+- `-v privatebin-data:/srv/data` - replace `privatebin-data` with the path to the folder on your system, where the
+  pastes and other service data should be persisted. This guarantees that your pastes aren't lost after you stop
+  and restart the image or when you replace it. Can be skipped if you just want to test the image.
+- `-p 8080:80` - The Nginx webserver inside the container listens on port 80, this parameter exposes it on your system
+  on port 8080. Be sure to use a reverse proxy for HTTPS termination in front of it in production environments.
+- `--read-only` - This image supports running in read-only mode. Using this reduces the attack surface slightly,
+  since an exploit in one of the images services can't overwrite arbitrary files in the container. Only /tmp, /var/tmp,
+  /var/run & /srv/data may be written into.
+- `-d` - launches the container in the background. You can use docker ps and docker logs to check if the container is
+  alive and well.
+- `--restart="always"` - restart the container if it crashes, mainly useful for production setups
+
+### Custom configuration
+
+In case you want to use a customized [conf.php](https://github.com/PrivateBin/PrivateBin/blob/master/cfg/conf.sample.php)
+file, for example one that has file uploads enabled or that uses a different template, add the file as a volume:
+
+```bash
+docker run -d --restart="always" --read-only -p 8080:80 -v conf.php:/srv/cfg/conf.php:ro -v privatebin-data:/srv/data privatebin/nginx-fpm-alpine:1.1.1
+```
+
+Note: Only the `Filesystem` data storage is supported, as the image doesn't include any PDO modules required for the
+`Database` one.
+
+## Rolling your own image
+
+To reproduce the image, just run:
+
+```bash
+docker build -t privatebin/nginx-fpm-alpine:1.1.1 .
+```
+
+### Behind the scenes
+
+The two processes, Nginx and php-fpm, are started by supervisord, which will also try to restart the services in case
+they crash.
+
+Nginx is required to serve static files and will also cache these for a bit. Requests to the index.php (which is the
+only PHP file exposed in the document root at /var/www) are passed on to php-fpm via fastCGI to port 9000. All other
+PHP files and the data are stored in /srv.
+
+The Nginx setup supports only HTTP, so make sure that you run another webserver as reverse proxy in front of this for
+HTTPS offloading and reducing the attack surface on your TLS stack. The Nginx in this image is set up to deflate/gzip
+text content.
+
+During the build of the image, the opcache & GD PHP modules are compiled from source and the PrivateBin release archive
+is downloaded from Github. All the downloaded Alpine packages and the PrivateBin archive are validated using cryptographic
+signatures to ensure the have not been tempered with, before deploying them in the image.

examples/00-phpinfo/docker-compose.yml

@@ -1,8 +0,0 @@
-version: '3'
-services:
-    backend:
-        build: ../../
-        volumes:
-        - './index.php:/var/www/index.php'
-        ports:
-        - '80:80'

examples/00-phpinfo/index.php

@@ -1,3 +0,0 @@
-<?php
-
-phpinfo();

examples/01-phpinfo-behind-https/Caddyfile

@@ -1,7 +0,0 @@
-https://* {
-    errors stderr
-    tls self_signed
-    proxy / http://backend:80 {
-        transparent
-    }
-}

examples/01-phpinfo-behind-https/docker-compose.yml

@@ -1,13 +0,0 @@
-version: '3'
-services:
-    backend:
-        build: ../../
-        volumes:
-        - './index.php:/var/www/index.php'
-
-    frontend:
-        image: abiosoft/caddy
-        volumes:
-        - './Caddyfile:/etc/Caddyfile'
-        ports:
-        - '443:443'

examples/01-phpinfo-behind-https/index.php

@@ -1,3 +0,0 @@
-<?php
-
-phpinfo();

examples/02-extra-headers/docker-compose.yml

@@ -1,9 +0,0 @@
-version: '3'
-services:
-    backend:
-        build: ../../
-        volumes:
-        - './index.html:/var/www/index.html'
-        - './headers.conf:/etc/nginx/location.d/headers.conf'
-        ports:
-        - '80:80'

examples/02-extra-headers/headers.conf

@@ -1,25 +0,0 @@
-# The X-Frame-Options header indicates whether a browser should be allowed
-# to render a page within a frame or iframe.
-add_header X-Frame-Options "SAMEORIGIN" always;
-
-# MIME type sniffing security protection
-# There are very few edge cases where you wouldn't want this enabled.
-add_header X-Content-Type-Options "nosniff" always;
-
-# The X-XSS-Protection header is used by Internet Explorer version 8+
-# The header instructs IE to enable its inbuilt anti-cross-site scripting filter.
-add_header X-XSS-Protection "1; mode=block" always;
-
-# Prevent mobile network providers from modifying your site
-#
-# (!) If you are using `ngx_pagespeed`, please note that setting
-# the `Cache-Control: no-transform` response header will prevent
-# `PageSpeed` from rewriting `HTML` files, and, if
-# `pagespeed DisableRewriteOnNoTransform off` is not used, also
-# from rewriting other resources.
-#
-# https://developers.google.com/speed/pagespeed/module/configuration#notransform
-add_header "Cache-Control" "no-transform";
-
-# Force the latest IE version
-add_header "X-UA-Compatible" "IE=Edge";

examples/02-extra-headers/index.html

@@ -1,3 +0,0 @@
-<h1>Extra Headers</h1>
-
-<p>Please open your browsers dev-tools to inspect the respone headers!</p>