dockhand 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb3565b6fe684a13404f48ae012095c671d1edd8b343cdae561b577dfec059e0
-  data.tar.gz: a848ca844f4e11abde42e535ba457a74469a86d4036c1a118a4607e7eb3e7b7c
+  metadata.gz: fa42658ae6a6ea4f1be74a573fcafc43696e7573d4752df296c643973906d89a
+  data.tar.gz: bfc3365a8e382a3f7ac8a449d3bdda69b181b27e38346f3a9458b74db70afa91
 SHA512:
-  metadata.gz: cc42d59510ccfd9e21b85cbdbcd448b907928e869b12dfa7a29eef7d04c0905ac9a711c9f5f1a6e4e21458f9e3efef86ac3f4c72674e9c18a2855b674d729d41
-  data.tar.gz: 34e9c0b08b8fe38a5b1c9b27ccbf74dc792466623922da5d5bae7a1e60afd362a1fb7b5b9cf69dd6beae61bb4a7957dea115253bc7312e8d3c7bb0b92d9a90ed
+  metadata.gz: 5907d0220a5bb352e6ec058cd37320a960b57bebbf46df0749e0fe619641366e1df0c70308e3f0a586b206a92747409ff8a367ed30f15c58d91072de5a401119
+  data.tar.gz: 0e031a75bbcdb07623478287040aa429604b7a83097043dfdbc251cf54a592dfa1aa99f33ef73bfb87d91c65d3841ee347da0c31e4b2cff47305db001b73c1e7

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.2.0
+
+* Drop support for Ruby < 3.4

data/Gemfile

@@ -7,4 +7,4 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "minitest", "~> 5.0"
+gem "minitest", "~> 6.0"

data/README.md

@@ -1,11 +1,139 @@
 # dockhand
 
-Toolkit for building Rails app Docker images.
+`dockhand` is a collection of helper commands that you can run *inside* a Docker
+container to set up a Rails application.
+
+  ```console
+  $ dockhand --help
+  Commands:
+    dockhand help [COMMAND]                     # Describe available commands or one specific command.
+    dockhand install-gems                       # Install gems with Bundler.
+    dockhand install-node                       # Install Node.js.
+    dockhand install-node-modules               # Install Node.js modules using Yarn, NPM, or PNPM.
+    dockhand install-packages [PACKAGES...]     # Install apt packages.
+    dockhand prepare-rails-app                  # Precompile assets, precompile code with Bootsnap, and normalize binstubs.
+    dockhand rails-entrypoint                   # Entrypoint for a Rails application.
+    dockhand transmute-to-artifacts [PATHS...]  # Move files and directories to an artifacts directory, and replace the originals with symlinks.
+  ```
+
+
+For example, in the following `Dockerfile`:
+
+  ```dockerfile
+  FROM ruby:3.4.0-slim
+
+  RUN gem install dockhand
+
+  WORKDIR /rails
+
+  COPY Gemfile Gemfile.lock .
+  RUN dockhand install-packages --buildtime --gem-buildtime --gem-runtime --clean \
+   && dockhand install-gems --clean
+
+  COPY . .
+  RUN dockhand prepare-rails-app --clean
+
+  ENV RAILS_ENV=production
+  ENTRYPOINT ["dockhand", "rails-entrypoint"]
+  CMD ["bin/rails", "server"]
+  EXPOSE 3000
+  ```
+
+* `dockhand install-packages ...` installs the apt packages needed for common
+  gems in the `Gemfile`, such as `libsqlite3-0` if using the `sqlite3` gem or
+  `postgresql-client` if using the `pg` gem.  Then it cleans up the apt cache
+  directories so the image won't contain unnecessary files.
+
+* `dockhand install-gems ...` installs the gems specified by `Gemfile.lock`,
+  treating the lock file as frozen to ensure reproducible builds.  Then it
+  cleans up Bundler's cache so the image won't contain unnecessary files.
+
+* `dockhand prepare-rails-app ...` precompiles code with [`bootsnap`][],
+  precompiles assets with a dummy `SECRET_KEY_BASE`, and fixes binstubs in
+  `bin/` for Windows users.  Then it cleans up the assets precompilation cache
+  so the image won't contain unnecessary files.
+
+  [`bootsnap`]: https://rubygems.org/gems/bootsnap
+
+* `dockhand rails-entrypoint` injects a call to `bin/rails db:prepare` if the
+  given command is `bin/rails server` (or an alias thereof).
+
+
+As another example, the following `Dockerfile` uses a [multi-stage build][] and
+precompiles assets using Node.js:
+
+  ```dockerfile
+  # Builder stage
+  FROM ruby:3.4.0-slim as builder
+
+  RUN gem install dockhand
+
+  WORKDIR /artifacts/rails
+
+  COPY Gemfile Gemfile.lock .
+  RUN dockhand install-packages --buildtime --gem-buildtime \
+   && dockhand install-gems --clean \
+   && dockhand transmute-to-artifacts $GEM_HOME
+
+  COPY .node-version package.json yarn.lock .
+  RUN dockhand install-node \
+   && dockhand install-node-modules
+
+  COPY . .
+  RUN dockhand prepare-rails-app --clean
+
+
+  # Application stage
+  FROM ruby:3.4.0-slim
+
+  RUN gem install dockhand
+
+  WORKDIR /rails
+
+  COPY Gemfile Gemfile.lock .
+  RUN dockhand install-packages --gem-runtime --clean
+
+  COPY --from=builder /artifacts /
+
+  ENV RAILS_ENV=production
+  ENTRYPOINT ["dockhand", "rails-entrypoint"]
+  CMD ["bin/rails", "server"]
+  EXPOSE 3000
+  ```
+
+* `dockhand transmute-to-artifacts ...` moves `/usr/local/bundle` (`$GEM_HOME`)
+  to `/artifacts/usr/local/bundle` and creates a symlink at `/usr/local/bundle`
+  that points to `/artifacts/usr/local/bundle`.  This makes it easy to copy gems
+  as artifacts from the builder stage to the final application stage, while
+  still allowing subsequent commands in the builder stage to use those gems.
+
+* `dockhand install-node` installs the appropriate version of Node.js based on
+  `.node-version`.  If you don't provide a `.node-version` file, it will try
+  to choose a version based on the `engines.node` value in `package.json`.
+
+* `dockhand install-node-modules` installs Node.js modules specified by
+  `yarn.lock`, using the appropriate version of Yarn and treating the lock file
+  as frozen to ensure reproducible builds.  It also supports NPM and PNPM lock
+  files.
+
+[multi-stage build]: https://docs.docker.com/build/building/multi-stage/
+
+
+***If you're looking for a more turn-key solution for your application's
+`Dockerfile`, including reduced build times using mounted caches, check out
+[`railbarge`][] which is built on `dockhand`.***
+
+[`railbarge`]: https://github.com/jonathanhefner/railbarge
 
 
 ## Installation
 
-Install the [`dockhand` gem](https://rubygems.org/gems/dockhand).
+Install the [`dockhand` gem](https://rubygems.org/gems/dockhand) in your
+`Dockerfile`:
+
+  ```dockerfile
+  RUN gem install dockhand
+  ```
 
 
 ## Contributing

data/lib/dockhand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dockhand
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dockhand
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jonathan Hefner
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-03-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -24,7 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-description: 
 email:
 - jonathan@hefner.pro
 executables:
@@ -45,10 +43,8 @@ homepage: https://github.com/jonathanhefner/dockhand
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/jonathanhefner/dockhand
   source_code_uri: https://github.com/jonathanhefner/dockhand
   changelog_uri: https://github.com/jonathanhefner/dockhand/blob/HEAD/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -56,15 +52,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Toolkit for building Rails app Docker images
 test_files: []