From f9687a65df7a680c8eee84471929af945dba650e Mon Sep 17 00:00:00 2001 From: El RIDO Date: Tue, 29 May 2018 19:09:14 +0200 Subject: [PATCH] improving documentation --- README.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8d935fa..81192e3 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,10 @@ where the server has zero knowledge of pasted data. Data is encrypted and decryp 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. +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 discussion avatars and the Nginx webserver to serve +static JavaScript libraries, CSS & the logos. All logs of php-fpm and Nginx (access & errors) are forwarded +to docker logs. ## Running the image @@ -19,38 +19,39 @@ the docker hub like this: 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: +The parameters in detail: - `-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. + and restart the image or when you replace it. May 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. + on port 8080. Be sure to use a reverse proxy for HTTPS termination in front of it for 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 +- `-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: +file, for example one that has file uploads enabled or that uses a different template, add the file as a second 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. +Note: The `Filesystem` data storage is supported out of the box. The image includes PDO modules for MySQL and SQLite, +required for the `Database` one, but you still need to keep the /srv/data persisted for the server salt and the traffic +limiter. ## Rolling your own image -To reproduce the image, just run: +To reproduce the image, run: ```bash -docker build -t privatebin/nginx-fpm-alpine:1.1.1 . +docker build -t privatebin/nginx-fpm-alpine . ``` ### Behind the scenes @@ -58,9 +59,9 @@ docker build -t privatebin/nginx-fpm-alpine:1.1.1 . 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. +Nginx is required to serve static files and caches them, too. 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