docs improved

This commit is contained in:
Christoph Haas 2025-06-05 01:05:43 +02:00
parent 3fd71d0354
commit ed31cb4184
3 changed files with 41 additions and 239 deletions

View file

@ -21,7 +21,7 @@ Some of the features that make it a good choice:
- handles Let's Encrypt certificates automatically
- deploying a new application version is done simply by _git push_
## Install Dokku
## Install with Dokku
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
@ -33,94 +33,79 @@ 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
Set the email address as a contact for Let's Encrypt:
dokku letsencrypt:set screenshots-beta.debian.net email haas@debian.org
dokku letsencrypt:set $DEBSHOTS_HOSTNAME email haas@debian.org
Create a new blank Dokku application:
dokku apps:create screenshots-beta.debian.net
dokku apps:create $DEBSHOTS_HOSTNAME
Create a new blank PostgreSQL database and link it to the application:
dokku postgres:create screenshots_beta
dokku postgres:link screenshots_beta screenshots-beta.debian.net
dokku postgres:create $DEBSHOTS_DB
dokku postgres:link $DEBSHOTS_DB $DEBSHOTS_HOSTNAME
Create a directory that will hold the screenshots' files:
mkdir -p /srv/www/screenshots-beta.debian.net/shrine
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 screenshots-beta.debian.net /srv/www/screenshots-beta.debian.net/shrine:/app/public/shrine
dokku storage:mount $DEBSHOTS_HOSTNAME $DEBSHOTS_IMAGEPATH:/rails/public/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 screenshots-beta.debian.net client-max-body-size 10m
dokku proxy:build-config screenshots-beta.debian.net
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 screenshots-beta.debian.net DEBSHOTS\_ALERT\_MESSAGE='This is a staging site. Uploads will not persist. Testing only.'
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='…'
dokku config:set --no-restart screenshots-beta.debian.net SALSA_OAUTH_SECRET='c4c137fcbbcb5d9c6ff98a76bbf45bceee77ebe13645198359a0fa38cd8fb1d0'
dokku config:set --no-restart screenshots-beta.debian.net SALSA_OAUTH_KEY='644440cd5595b3b7aea6e959ab1488e7026c2b5cf24faea8f9af5ce914377d52'
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.
Now make Dokku fetch the Docker image and start a container from it:
Finally create an admin user for moderation:
dokku git:from-image $DEBSHOTS_HOSTNAME registry.salsa.debian.org/debian/debshots:main-3fd71d03
Start a Rails console:
Once the application is running, enter the container and create a new admin user:
rails c -e production
Create a new user record:
user = User.create(realname: 'Christoph Haas', password: 'foobartest', email: 'email@christoph-haas.de')
user.save!
dokku enter $DEBSHOTS_HOSTNAME
bin/rails 'debshots:create_admin[email,password]'
## Cron jobs
Get the latest information on packages from the Debian repositories.
Create cron jobs (e.g. daily) to get the latest information on packages from the Debian repositories:
bundle exec rails debshots:update_from_deb_repos RAILS_ENV=production
bundle exec rails debshots:update_longdescription_from_deb_repos RAILS_ENV=production
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
@ -128,7 +113,7 @@ 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.
but they have to be created manually.
Anonymous uploads are possible but they have to be moderated by an administrator.
@ -164,43 +149,3 @@ this time.)
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
# Frequent update of Debian SSO certificate
Run /etc/nginx/update-sso-ca regularly to update the CA certificate and the CRL.
The CRL (certificate revocation list) is only valid for three days. So make sure
you have a daily cron job for the updates. Do not forget to restart Nginx afterwards.
Otherwise you will end up with this error message:
400 Bad Request
The SSL certificate error
nginx

View file

@ -1,145 +0,0 @@
# Installing debshots
One way to deploy the application is using Ansible.
(This method has not been used for a while. Expect breakages.)
Take a fresh Debian Buster server (8 GB RAM recommended).
You can use an existing server but be aware that the Ansible
playbook will assume it can use the TCP ports 80 and 443 and
be able to add PostgreSQL database users.
On the server check out this Git repository from
https://salsa.debian.org/debian/debshots
Also install PIP to get a recent version of Ansible there:
apt install python3-pip
pip3 install ansible
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(name: 'Christoph Haas', password: 'foobartest', email: 'email@christoph-haas.de', provider: 'local')
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]
Get the latest information on packages from the Debian repositories.
bundle exec rails debshots:update_from_deb_repos RAILS_ENV=production
bundle exec rails debshots:update_longdescription_from_deb_repos RAILS_ENV=production
# 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 (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.
# 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
# Frequent update of Debian SSO certificate
Run /etc/nginx/update-sso-ca regularly to update the CA certificate and the CRL.
The CRL (certificate revocation list) is only valid for three days. So make sure
you have a daily cron job for the updates. Do not forget to restart Nginx afterwards.
Otherwise you will end up with this error message:
400 Bad Request
The SSL certificate error
nginx

View file

@ -1,3 +1,5 @@
_Only local users (in the database) and single-sign-on via salsa.debian.org are currently supported._
# Authentication
The application uses _omniauth_ to allow local authentication for moderators