added docker development environment

.simplecov

@@ -1,4 +1,4 @@
-if ENV['RUN_SIMPLECOV']
+if ENV['RUN_SIMPLECOV'] == 'true'
   SimpleCov.command_name 'main'
   SimpleCov.start do
     add_filter %r{^/test/}

Rakefile

@@ -81,7 +81,7 @@ task :test => [ :test_main,
                 :test_shared,
                 :test_shared_combo ]
 
-if ENV['RUN_RUBOCOP']
+if ENV['RUN_RUBOCOP'] == 'true'
   require "rubocop/rake_task"
   RuboCop::RakeTask.new(:rubocop) do |t|
     t.options = `git ls-files -z`.split("\x0")     # limit rubocop to the files in the repo

apps/basic_app.ru

@@ -14,7 +14,7 @@ require 'pagy'
 require 'pagy/extras/navs'
 require 'pagy/extras/items'
 require 'pagy/extras/trim' if ENV['ENABLE_TRIM']
-require 'oj' if ENV['ENABLE_OJ']
+require 'oj' if ENV['ENABLE_OJ'] == 'true'
 
 # sinatra setup
 require "sinatra/base"

docker/README.md

@@ -0,0 +1,80 @@
+# Pagy on Docker
+
+This dir contains a few files to setup a development environment without installing anything on your system.
+
+You can use it to develop changes, run tests and check a live preview of the documentation.
+
+### Overview
+
+The pagy docker environment has been designed to be useful for developing:
+
+- It provides the infrastructure required (right version of ruby, jekyll server, env variable, tests, etc.) without the hassle to install and maintain anything in your system
+- The local `pagy` dir is mounted at the container dir `/opt/project` so you can edit the files in your local pagy dir or in the container: they are the same files.
+- The gems are installed in the container `BUNDLE_PATH=/usr/local/bundle` and that dir is `chown`ed to your user, and mounted as the docker volume `pagy_bundle`. You can use the `bundle` command and it will be persisted in the volume, no need to rebuild the image nor pollute your own system.
+- Your container user `HOME` is preserved in the `pagy_user_home` volume, so you can even get back to the shell history in future sessions.
+
+
+## Prerequisites
+
+- recent `docker`
+- recent `docker-compose`
+- basic knowledge of docker/docker-compose
+
+## Start it
+
+Set in your IDE or system a few variables about your user:
+
+- the `GROUP` name (get it with `id -gn` in the terminal)
+- the `UID` (get it with `id -u` in the terminal)
+- the `GID` (get it with `id -g` in the terminal)
+
+You can also specify a few other variables used in the `docker-compose.yml` file.
+
+If you already set the variables:
+
+```sh
+cd docker
+docker-compose build pagy3 pagy-jekyll
+```
+
+or just set it with the command. For example:
+
+```sh
+cd docker
+GROUP=dd UID=1000 GID=1000 && docker-compose build pagy pagy-jekyll
+```
+
+The first time it will also build the images, from then on it will just run the containers for the pagy environment (you can inspect the `docker-compose.yml` file for more details).
+
+## Use it
+
+Run the containers from the docker dir:
+
+```sh
+docker-compose up
+```
+
+Open a terminal in the pagy container and run the usual `bundle install` to install the gems into the `pagy_bundle` volume.
+
+Then you cou can run `irb -Ilib -r pagy` from the container in order to have `pagy` loaded and ready to try.
+
+Run all the tests by simply running `rake` without arguments.
+
+The `gh-pages` service runs the jekyll server so you can edit the docs files from the local `pagy` dir and have a real-time preview of your changes at `http://localhost:4000`. You don't even need to reload the page in the browser to see the change you do in the `*.md` page file.
+
+If you are serious about developing, you can integrate this environment with some good IDE that provides docker and ruby integration. I currently use it for all the basic pagy development, fully integrated with [RubyMine](https://www.jetbrains.com/ruby/?from=https%3A%2F%2Fgithub.com%2Fddnexus%2Fpagy).
+
+## Clean up
+
+When you want to get rid of everything related to the `pagy` development on your system:
+
+- `rm -rf /path/to/pagy`
+- `docker rmi pagy pagy-gh-pages` or `docker rmi pagy:3 pagy-gh-pages` if you don't want to remove other versions (e.g. `pagy:4`)
+- `docker volume rm pagy3_bundle pagy3_user_home pagy3_docs_site`
+- `docker system prune` (not pagy related but good for reclaiming storage space from docker)
+
+## Caveats
+
+- If you use different pagy images for different pagy versions/branches:
+  - Remember to checkout the right branch before using it
+  - If you test with `RUN_SIMPLECOV` you may need to `rm -rf coverage` or you may get some error that will not allow you to test

docker/docker-compose.yml

@@ -0,0 +1,69 @@
+# Basic docker development environment
+# it will keep the installed gems and HOME in the pagy_bundle and pagy_user_home docker volumes
+# the gh-pages service will be updating a live preview for the documentation
+
+
+version: "3.8"
+
+services:
+
+  pagy:
+    image: pagy:3
+    build:
+      context: .
+      dockerfile: pagy.dockerfile
+      # set env variables with your user info
+      args:
+        user: $USER
+        group: $GROUP
+        uid: $UID
+        gid: $GID
+        password: "${PASSWORD:-rubydev}"
+        term: ${TERM:-xterm-256color}
+    container_name: pagy3
+    volumes:
+      - ../.:/opt/project
+      - bundle:/usr/local/bundle
+      - user_home:/home/$USER
+    environment:
+      - ENABLE_OJ=${ENABLE_OJ:-true}
+      - RUN_SIMPLECOV=${RUN_SIMPLECOV:-true}
+      - RUN_RUBOCOP=${RUN_RUBOCOP:-true}
+    stdin_open: true
+    tty: true
+
+  pagy-jekyll:
+    image: pagy-jekyll:latest
+    build:
+      context: .
+      dockerfile: pagy-jekyll.dockerfile
+    container_name: pagy-jekyll
+    environment:
+      - JEKYLL_GITHUB_TOKEN=${JEKYLL_GITHUB_TOKEN}
+    ports:
+      - "4000:4000"
+      - "35729:35729"
+    volumes:
+      - ../docs:/opt/docs
+      - docs_site:/opt/site
+    command: |
+      jekyll serve \
+          --incremental \
+          --livereload \
+          --watch \
+          --force-polling \
+          --host 0.0.0.0 \
+          --baseurl '' \
+          --source /opt/docs \
+          --destination /opt/site
+    stdin_open: true
+    tty: true
+
+volumes:
+  bundle:
+    name: pagy3_bundle
+  user_home:
+    name: pagy3_user_home
+  docs_site:
+    name: pagy3_docs_site
+

docker/pagy-jekyll.dockerfile

@@ -0,0 +1,20 @@
+FROM ruby:2-alpine
+
+WORKDIR /opt
+
+# one step to exclude .build_deps from docker cache
+RUN apk update \
+ && apk add --no-cache --virtual .build_deps make build-base \
+ && echo "source 'https://rubygems.org'" > Gemfile \
+ && echo "gem 'github-pages', '212', group: :jekyll_plugins" >> Gemfile \
+ && bundle install \
+ && apk del .build_deps
+
+ENV LANG=en_US.UTF-8 \
+    LANGUAGE=en_US.UTF-8 \
+    LC_ALL=en_US.UTF-8
+
+CMD ["jekyll", "serve", "-H", "0.0.0.0", "-P", "4000"]
+
+EXPOSE 4000 35729
+VOLUME /opt/site

docker/pagy.dockerfile

@@ -0,0 +1,56 @@
+FROM ruby:2.7
+
+
+ARG term
+ENV TERM="${term:-xterm-256color}"
+
+# install required packages
+RUN apt-get update && apt-get install -y locales \
+ && sed -i 's/^# *\(en_US.UTF-8\)/\1/' /etc/locale.gen \
+ && locale-gen \
+ && apt-get install -y \
+        nodejs \
+        git \
+        nano
+
+ARG user
+ARG group
+ARG uid
+ARG gid
+ARG password=rubydev
+
+# setup users and .bashrc
+#   - same pasword for user and root
+#   - color prompt for user and root
+RUN groupadd --gid=$gid --force $group \
+ && useradd --uid=$uid --gid=$gid --shell=/bin/bash --create-home $user \
+ && echo $user:$password | chpasswd \
+ && echo root:$password | chpasswd \
+ && sed -i 's/#force_color_prompt=yes/force_color_prompt=yes/' /home/$user/.bashrc \
+ && sed -i 's/\\u@\\h\\\[\\033\[00m\\\]:\\\[\\033\[01;34m\\\]\\w\\\[\\033\[00m\\\]/\\u \\\[\\033\[01;34m\\\]\\w\\\[\\033\[00m\\\] /' /home/$user/.bashrc \
+ && cp /home/$user/.bashrc /root/.bashrc
+
+ENV \
+    BUNDLE_PATH=/usr/local/bundle \
+    GEM_HOME=/usr/local/bundle \
+    BUNDLE_APP_CONFIG=/usr/local/bundle \
+    BUNDLE_BIN=/usr/local/bundle/bin \
+    BUNDLE_SILENCE_ROOT_WARNING=1 \
+    BUNDLE_CACHE_ALL=1 \
+    LS_OPTIONS='--color=auto' \
+    EDITOR=nano \
+    TERM=${term:-xterm-256color} \
+    SHELL=/bin/bash \
+    LANG=en_US.UTF-8 \
+    LANGUAGE=en_US.UTF-8 \
+    LC_ALL=en_US.UTF-8
+
+RUN chown -R $uid:$gid $BUNDLE_PATH
+
+WORKDIR /opt/project
+
+VOLUME \
+    /home/$user \
+    $BUNDLE_PATH
+
+USER $user

test/pagy/extras/elasticsearch_rails_test.rb

@@ -5,7 +5,7 @@
 require_relative '../../mock_helpers/elasticsearch_rails'
 require 'pagy/extras/overflow'
 
-SimpleCov.command_name 'elasticsearch' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'elasticsearch' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy::Search do
 

test/pagy/extras/i18n_test.rb

@@ -5,7 +5,7 @@
 require 'i18n'
 require 'pagy/extras/i18n'
 
-SimpleCov.command_name 'i18n' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'i18n' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy::Frontend do
 

test/pagy/extras/items_test.rb

@@ -7,7 +7,7 @@
 require_relative '../../mock_helpers/searchkick'
 require 'pagy/extras/items'
 
-SimpleCov.command_name 'items' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'items' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy::Backend do
 

test/pagy/extras/overflow_test.rb

@@ -4,7 +4,7 @@
 require_relative '../../test_helper'
 require 'pagy/extras/overflow'
 
-SimpleCov.command_name 'overflow' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'overflow' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy do
 

test/pagy/extras/searchkick_test.rb

@@ -5,7 +5,7 @@
 require_relative '../../mock_helpers/searchkick'
 require 'pagy/extras/overflow'
 
-SimpleCov.command_name 'elasticsearch' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'elasticsearch' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy::Search do
 

test/pagy/extras/shared_combo_test.rb

@@ -5,7 +5,7 @@
 require 'pagy/extras/items'
 require 'pagy/extras/trim'
 
-SimpleCov.command_name 'shared_combo' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'shared_combo' if ENV['RUN_SIMPLECOV'] == 'true'
 
 # add tests for oj and pagy_id
 describe Pagy::Frontend do

test/pagy/extras/shared_test.rb

@@ -1,13 +1,13 @@
 # encoding: utf-8
 # frozen_string_literal: true
 
-if ENV['ENABLE_OJ']
+if ENV['ENABLE_OJ'] == 'true'
 
   require_relative '../../test_helper'
   require 'oj' # all the other tests run without Oj
   require 'pagy/extras/shared'
 
-  SimpleCov.command_name 'shared' if ENV['RUN_SIMPLECOV']
+  SimpleCov.command_name 'shared' if ENV['RUN_SIMPLECOV'] == 'true'
 
   # add tests for oj and pagy_id
   describe Pagy::Frontend do

test/pagy/extras/support_test.rb

@@ -5,7 +5,7 @@
 require 'pagy/extras/support'
 require 'pagy/countless'
 
-SimpleCov.command_name 'support' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'support' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy::Frontend do
 

test/pagy/extras/trim_test.rb

@@ -10,7 +10,7 @@
 require 'pagy/extras/semantic'
 require 'pagy/extras/trim'
 
-SimpleCov.command_name 'trim' if ENV['RUN_SIMPLECOV']
+SimpleCov.command_name 'trim' if ENV['RUN_SIMPLECOV'] == 'true'
 
 describe Pagy::Frontend do
 

test/test_helper.rb

@@ -3,9 +3,9 @@
 
 require 'bundler/setup'
 
-require 'simplecov' if ENV['RUN_SIMPLECOV']
+require 'simplecov' if ENV['RUN_SIMPLECOV'] == 'true'
 
-if ENV['RUN_CODECOV']
+if ENV['RUN_CODECOV'] == 'true'
   require 'codecov'
   SimpleCov.formatter = SimpleCov::Formatter::Codecov
 end