docs improved
This commit is contained in:
parent
3fd71d0354
commit
ed31cb4184
3 changed files with 41 additions and 239 deletions
|
|
@ -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 screenshots-beta.debian.net SALSA_OAUTH_SECRET='c4c137fcbbcb5d9c6ff98a76bbf45bceee77ebe13645198359a0fa38cd8fb1d0'
|
||||
dokku config:set --no-restart screenshots-beta.debian.net SALSA_OAUTH_KEY='644440cd5595b3b7aea6e959ab1488e7026c2b5cf24faea8f9af5ce914377d52'
|
||||
dokku config:set --no-restart $DEBSHOTS_HOSTNAME SALSA_OAUTH_SECRET='…'
|
||||
dokku config:set --no-restart $DEBSHOTS_HOSTNAME SALSA_OAUTH_KEY='…'
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue