debshots/doc/README.Development.md

5.6 KiB

Developing/Contributing

This document helps you set up the debshots Rails application on your own Debian system if you intend to work on the source code.

Preparing the development environment

Install dependencies

These APT-gettable packages are required to run the application:

sudo apt install ruby-dev libssl-dev libreadline-dev \
    zlib1g-dev libbz2-dev libpq-dev git imagemagick

Prepare PostgreSQL database server and user

PostgreSQL stores data about packages, screenshots and users. Authentication works in production because the applications runs as the system user debshots that gets access to PostgreSQL via ident-based authentication. In development mode you will likely work as your own user so you need to create a development database in PostgreSQL and create a database user with a password to access it. Put those credentials into ./config/database.yml

sudo apt install postgresql
sudo su - postgres
createuser -P -d debshots
# The password will have to match that in config/database.yml
createdb -O debshots -E UTF8 -T template0 debshots_dev

Install the required Ruby version using rbenv

Rails uses the bundler tool to download and install dependent gems/packages. To avoid installing them system wide you should rather create an rbenv sandbox environment where the specific Ruby version and the required gems are installed. That ensures stable operation of the application and does not spoil your otherwise APT-controlled system.

Documentation on rbenv can be found at https://github.com/rbenv/rbenv

To install it for your current user:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile

As an upright Debian user we should use Debian packages. But this application (as most web applications) requires specific versions of libraries and modules. So rbenv isolates them from the rest of the system.

Load rbenv automatically by appending

the following to ~/.profile:

Run "rbenv init" and do as said.

Install the "rbenv install" (https://github.com/rbenv/ruby-build#readme) add-on:

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Get the application

Clone the debshots Git repository from https://salsa.debian.org/debian/debshots

Install the required Ruby version and the applications' dependencies

rbenv install
echo "gem: --no-rdoc --no-ri" > ~/.gemrc
gem install bundler

If this command complains that it cannot write into /var/lib/gems/… then please source your ~/.profile or ~/.zshrc or open a new terminal window to let rbenv take over.

bundle install

Optional: copy screenshots and database from the live website

To make database access easier you can create a ~/.pgpass file like:

127.0.0.1:5432:debshots_dev:debshots_dev:thepassword

Don't forget to "chown 0600" that file.

scp screenshots.debian.net:debshots-screenshots.tar .
tar -C public/ -xvf debshots-screenshots.tar
scp screenshots.debian.net:debshots.sql .
psql -h 127.0.0.1 debshots_dev debshots-dev < debshots.sql

Make sure that the application's database schema is upgraded to reflect the latest state of development.

bundle exec rails db:migrate

(The reason to prefix all commands by "bundle exec" to make sure that the Ruby version from rbenv is used and that only the gems from the sandbox environment are used.)

Start with a blank database

Create a blank database with the latest database schema:

bundle exec rails db:schema:load

If you get database access errors then check the development section in your ./config/database.yml file.

Fill/update the database with information from APT repositories

Get the latest information on packages from the Debian repositories.

bundle exec rails debshots:update_from_deb_repos
bundle exec rails debshots:update_longdescription_from_deb_repos

Run the application

bundle exec rails s

Point your browser to http://localhost:3000/ and you will see the web site.

bundle exec rake 'debshots:create_admin[john@example.org,mydirtysecret]'

Optional: Tidy up the screenshot data

bundle exec rake debshots:remove_broken_screenshots
bundle exec rake debshots:remove_duplicate_images

Optional: Import new package information

bundle exec rake debshots:list_deb_repos
bundle exec rake debshots:update_from_deb_repos
bundle exec debshots:update_longdescription_from_deb_repos

To run the Rails server in development mode on port 3001 with HTTPS:

rails s puma -b 'ssl://0.0.0.0:3001?key=nginx/localhost.key&cert=nginx/localhost.crt&verify_mode=none'

This is required to be able to use single-sign login with the different services.

If you keep config.action_dispatch.x_sendfile_header = 'X-Sendfile' in your config/development.rb file, then you need to point your browser to the port of the "thrust" process. In Procfile.dev it is set to port 3001. In that case the Rails application runs on port 3000 and will not deliver files (e.g. images and other assets). In that case use localhost:3001 in your browser.

Production installation

Building a Docker image is the recommended way to prepare Debshots for production.

docker build -t debshots .

Use docker-compose.yml as a starting point to try it out.

In the last 10 years, Debshots was deployed using Dokku. But Coolify, Portainer or just docker-compose are also good options.

Noteworthy URLs

Lucide icons: https://lucide.dev/icons

Icons module: https://github.com/Rails-Designer/rails_icons

Zurb foundation SCSS variables: https://get.foundation/sites/docs