# Installing debshots on Dokku (This document is not up to date.) ## What is Dokku? [Dokku](https://dokku.com/) is an open-source software that helps deploy web applications. Once installed and set up you essentially do a _git push_ and Dokku will do its magic. It works similar to Heroku (a paid service) and even uses Heroku's _buildpacks_ for that purpose. It can handle common web frameworks like Ruby-on-Rails. It has been used for screenshots.debian.net in production for several years. Some of the features that make it a good choice: - healthchecks (will refuse to deploy if your new version is failing) - seamless deployment (no downtime while switching to the new version) - provides persistent volumes (where screenshots are stored) - provides a PostgreSQL database and tells the application how to access it through an automatic environment variable - handles Let's Encrypt certificates automatically - deploying a new application version is done simply by _git push_ ## Install with Dokku (One unsolved issue with Dokku is that I cannot deploy an nginx.conf.sigil template to customze the Nginx behavior. So using X-Sendfile to improve the delivery of images is not possible.) Grab a (virtual) server with at least 3 GB of RAM and 20 GB of SSD space. The application is currently run on a Hetzner server in Germany that costs less than 5€ per month. Follow the installation instructions on https://dokku.com/ Install the _Let's Encrypt_ plugin: dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git For simplicity set a few variables to avoid repetitions during setup: export DEBSHOTS_HOSTNAME=screenshots-beta.debian.net export DEBSHOTS_DB=screenshots_beta export DEBSHOTS_IMAGEPATH=/srv/www/screenshots-beta.debian.net/shrine Create a new blank Dokku application: dokku apps:create $DEBSHOTS_HOSTNAME Set the email address as a contact for Let's Encrypt: dokku letsencrypt:set $DEBSHOTS_HOSTNAME email haas@debian.org Create a new blank PostgreSQL database and link it to the application: dokku postgres:create $DEBSHOTS_DB dokku postgres:link $DEBSHOTS_DB $DEBSHOTS_HOSTNAME Create a directory that will hold the screenshots' files: mkdir -p DEBSHOTS_IMAGEPATH Make sure that its ownership matches the user's ID used in the Docker container. chown -R 1000:1000 $DEBSHOTS_IMAGEPATH Mount it into the application's path: dokku storage:mount $DEBSHOTS_HOSTNAME $DEBSHOTS_IMAGEPATH:/rails/shrine By default the Nginx (that Dokku provides) will only allow uploads up to 1 MB. You may want to increase that limit: dokku nginx:set $DEBSHOTS_HOSTNAME client-max-body-size 10m dokku proxy:build-config $DEBSHOTS_HOSTNAME If you want to add a message that gets printed on all pages you can set an environment variable for that purpose: dokku config:set $DEBSHOTS_HOSTNAME DEBSHOTS\_ALERT\_MESSAGE='This is a staging site. Uploads will not persist. Testing only.' To enable single-sign-on with salsa.debian.net, you need to set the secret and key for OAuth: dokku config:set --no-restart $DEBSHOTS_HOSTNAME SALSA_OAUTH_SECRET='…' dokku config:set --no-restart $DEBSHOTS_HOSTNAME SALSA_OAUTH_KEY='…' Set an SMTP server for notification emails: dokku config:set --no-restart $DEBSHOTS_HOSTNAME SMTP_SERVER=dokku2.workaround.org 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. Now make Dokku fetch the Docker image and start a container from it: dokku git:from-image $DEBSHOTS_HOSTNAME registry.salsa.debian.org/debian/debshots:latest Once the application is running, enter the container and create a new admin user: dokku enter $DEBSHOTS_HOSTNAME bin/rails 'debshots:create_admin[john@example.org,mysecret]' ## Cron jobs Create cron jobs (e.g. daily) to get the latest information on packages from the Debian repositories: dokku run $DEBSHOTS_HOSTNAME bin/rails debshots:update_from_deb_repos dokku run $DEBSHOTS_HOSTNAME bin/rails debshots:update_longdescription_from_deb_repos You may do some house keeping from time to time: dokku run $DEBSHOTS_HOSTNAME bin/rails debshots:remove_broken_screenshots dokku run $DEBSHOTS_HOSTNAME bin/rails debshots:remove_duplicate_images _Replace $DEBSHOTS_HOSTNAME with the actual host name._ # 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 they have to be created manually. Anonymous uploads are possible but they have to be moderated by an administrator. # Authorization (not yet implemented) 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.