Documentation revamped

doc/README.Installation.md

@@ -0,0 +1,129 @@
+# Installing debshots
+
+The easiest way to deploy the application is using Ansible.
+
+Take a Debian Stretch server (8 GB RAM recommended).
+
+Install PIP to get a recent version of Ansible:
+
+    apt install python-pip
+    pip install ansible
+
+Run the Ansible playbook that comes with the debshots repository:
+
+    cd ansible
+    ansible-playbook debshots.yml
+
+Check out the project repository from https://salsa.debian.org/debian/debshots
+
+Change to the *ansible* subdirectory and run the main playbook:
+
+    cd ansible
+    ansible-playbook debshots.yml
+
+This will install PostgreSQL and Nginx, create a database, create a system user
+and do various configuration.
+
+Make sure that you set the environment variables as described in README.SSO.md before
+you start the Rails application. Otherwise most single sign-on providers cannot work.
+You also need to get the https://salsa.debian.org/debsso-team/debsso/raw/master/update-debsso-ca
+script and run it in /etc/nginx to update the certficate and CRL used by the Debian
+single-sign-on provider.
+
+The production configuration uses Nginx that decrypts HTTPS and either serves static
+assets (images, Javascript, CSS) itself or requests for dynamic content to the
+Rails application. You will need a SSL certificate for Nginx. Just get one from
+LetsEncrypt using the *certbot* tool.
+
+Finally create an admin user for moderation:
+
+Start a Rails console:
+
+    rails c -e production
+
+Create a new user record:
+
+    user = User.create(realname: 'Christoph Haas', password: 'foobartest', email: 'email@christoph-haas.de')
+    user.save!
+
+## Cron jobs
+
+Parse Nginx access logs to count the number of visits of each package:
+
+    RAILS_ENV=production bundle exec rake debshots:accesslog2visits[/var/log/nginx/cache-access.log.1]
+
+As a cron job:
+
+    41 9 * * * cd $HOME/debshots ; RAILS_ENV=production /home/debshots/.rbenv/shims/bundle exec rake debshots:accesslog2visits[/var/log/nginx/cache-access.log.1]
+
+# Authentication
+
+This web application tries to avoid to create yet another directory
+of user accounts. So it leverages other common web sites like StackExchange,
+Debian SSO (using browser/client certificates) or GitHub as single-sign-on
+services. It is still possible to create local user accounts for administrators
+but registration is disabled.
+
+Anonymous uploads are possible but they have to be moderated by an administrator.
+
+# Authorization
+
+A user can have one of these access levels.
+
+## Anonymous
+
+Without authentication all user actions are moderated. Such users can upload
+screenshots or report existing/published screenshots as inappropriate. However
+a user with level 'admin' will have to approve that action.
+
+## Authenticated by single-sign-login (SSO)
+
+Users can use different authentication services to login - like Github or
+StackExchange. Such users internally get an account with a random password
+created but they will keep logging in via SSO.
+
+The first upload will have to be moderated. Subsequent uploads will be
+approved automatically.
+
+## Authenticated by Debian signle-sign-login (SSO)
+
+If a user authenticates using a Debian SSO client certificate they will be
+able to upload screenshots without moderation.
+(Anohter idea was to restrict them to uploading only screenshots for the
+packages they maintain. But that may be reliable and is not implemented at
+this time.)
+
+## Administrator
+
+Such a user has an internal user account. The database record has the
+'admin' field set to 1. Admins can freely upload, moderate and delete
+screenshots. They can also read the log files.
+
+# Nginx during development
+
+During development it is advised to run Nginx to proxy ports 3000 (HTTP)
+and 3001 (HTTPS) to the rails application.
+
+    cd nginx
+    nginx -c `pwd`/nginx.conf
+
+The SSL certitificate is just a self-signed certificate with the
+common name "localhost". It was generated using:
+
+    openssl req -x509 -newkey 4096 -nodes -keyout localhost.key -out localhost.crt -days 3650
+
+Run "rails s" in another window. That will use the built-in Ruby 'Puma'
+application server that can also be used in production. It requires less
+configuration than Phusion Passenger but may be slower in regard to
+performance and multi-threading / multi-core support.
+
+If you get "400 Bad Request / The SSL certificate error" in the browser then
+please check the error log (/tmp/error*). Once cause is that the CRL of
+the Debian SSO has expired and needs to be updated.
+
+# Tidy up the screenshot data:
+
+bundle exec rake debshots:remove_broken_screenshots
+
+bundle exec rake debshots:remove_duplicate_images
+