Skip to content

Commit

Permalink
added docker development environment
Browse files Browse the repository at this point in the history
  • Loading branch information
ddnexus committed Mar 8, 2021
1 parent ef8b4bc commit 467b985
Show file tree
Hide file tree
Showing 17 changed files with 240 additions and 15 deletions.
2 changes: 1 addition & 1 deletion .simplecov
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
if ENV['RUN_SIMPLECOV']
if ENV['RUN_SIMPLECOV'] == 'true'
SimpleCov.command_name 'main'
SimpleCov.start do
add_filter %r{^/test/}
Expand Down
2 changes: 1 addition & 1 deletion Rakefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion apps/basic_app.ru
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
80 changes: 80 additions & 0 deletions docker/README.md
Original file line number Diff line number Diff line change
@@ -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
69 changes: 69 additions & 0 deletions docker/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -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

20 changes: 20 additions & 0 deletions docker/pagy-jekyll.dockerfile
Original file line number Diff line number Diff line change
@@ -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
56 changes: 56 additions & 0 deletions docker/pagy.dockerfile
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion test/pagy/extras/elasticsearch_rails_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/i18n_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/items_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/overflow_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/searchkick_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/shared_combo_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions test/pagy/extras/shared_test.rb
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/support_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion test/pagy/extras/trim_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions test/test_helper.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 467b985

Please sign in to comment.