Documentation revamped
This commit is contained in:
parent
844feb7f0e
commit
fbee80f5f1
16 changed files with 377 additions and 1175 deletions
123
doc/README.Development.md
Normal file
123
doc/README.Development.md
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
# 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
|
||||
|
||||
Most steps required to deploy the application (for production use) are automated
|
||||
using an Ansible playbook that you find at ./ansible/debshots.yml
|
||||
|
||||
The following section documents the steps you need to do to get the application
|
||||
running in development mode. If you are a little experienced in developing Rails
|
||||
applications you may know most of that already.
|
||||
|
||||
Development worked best on a Debian Jessie or Sid system.
|
||||
|
||||
## Install dependencies
|
||||
|
||||
These APT-gettable packages are probably required to run the application:
|
||||
|
||||
apt install python-psycopg2 ruby sudo 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
|
||||
|
||||
apt install postgresql
|
||||
su - postgres
|
||||
createuser -P -d debshots_dev
|
||||
createdb -O debshots_dev -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
|
||||
|
||||
# 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
|
||||
bundle install
|
||||
|
||||
## Optional: copy screenshots and database from the live website
|
||||
|
||||
scp screenshots.debian.net:debshots-screenshots.tar .
|
||||
tar -C public/ -xvf debshots-screenshots.tar
|
||||
scp screenshots.debian.net:debshots.sql .
|
||||
psql 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 RAILS_ENV=production
|
||||
bundle exec rails debshots:update_longdescription_from_deb_repos RAILS_ENV=production
|
||||
|
||||
## Run the application
|
||||
|
||||
bundle exec rails s
|
||||
|
||||
Point your browser to http://localhost:3000/ and you will see the web site.
|
||||
|
||||
## 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue