Skip to content
Basic dibspack(s) for common operations/features
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
git
install
perl
procfile
wrapexec
README.adoc
expand-in-file
lib.sh
prereqs
shellrun

README.adoc

Basic dibspacks

This repository contains some basic dibspacks that can be used with dibs. To use them, you can…​

  • …​ put a git reference to the main repository, e.g.:

packs:
  foo:
    type: git
    origin: https://github.com/polettix/dibspack-basic
  • …​ use it from a stroke:

actions:
    some-stroke:
        pack: foo
        path: perl/build
        user: ubuntu

git/fetch

This dibspack helps checking out a git repository. It is called like this:

git/fetch [git_uri]

where the optional parameter is a URI where the code can be found. In case this parameters is absent, environment variable DIBSPACK_GIT_URI is used instead (or an exception is thrown if this is not defined properly too).

The git URI can include a fragment section, interpreted as whatever comes after the first dash character #. When present, the fragment represents the ref to check out; by default, the master branch is considered. This can help pinning a specific revision and avoid surprises due to updates.

The checkout is performed in the src_dir directory, i.e. the directory passed via the DIBS_DIR_SRC envile. If this directory already contains a .git sub-directory and environment variable DIBSPACK_GIT_REFRESH is set to 1 (exactly), then the current contents will be used for a fetch from the current origin remote. Otherwise, the src_dir is wiped out completely and the remote is cloned to get a fresh copy.

It is possible to set variable DIBSPACK_GIT_DEBUG to 1 (exactly) and activate the shell’s capabilities for debugging (options -x and '-v').

Example usage in a dibs.yml file:

packs:
  foo:
    type:   git
    origin: https://github.com/polettix/dibspack-basic
actions:
  bar:
    pack: foo
    path: git/fetch
    args: ['https://github.com/polettix/sample-mojo#844f256']

This dibspack requires git to be available in the container; it contains some scripts to assist in the installation of git depending on the operating system tools inside the container (e.g. Alpine, Debian, …​).

install/plain-copy

This buildpack copies files from a source to a destination. It is invoked like this:

install/plain-copy source destination

If source is missing or empty, src_dir is used instead (according to the contents of envile DIBS_DIR_SRC). If destination is empty, path /app is used instead.

This dibspack tries hard to get rid of destination before starting the copy.

The copy is done using cp -pPR to keep the same permissions as in the source.

Example usage in a dibs.yml file:

packs:
  foo:
    type:   git
    origin: https://github.com/polettix/dibspack-basic
actions:
  bar:
    pack: foo
    path: install/plain-copy
    args: [{path_cache: '/app'}, '/app']

install/with-dibspack

This buildpack copies files from a source to a destination, pruning those that match patterns defined inside a file. This allows selecting only part of the files in a wider source, leaving behind those that possibly help building/testing artifacts but are then unneeded in the normal runtime phase.

It is invoked like this:

install/with-dibspack [options...] [step]

This program is a Perl program and supports flexible GNU-style parameters:

  • --debug/-D: boolean option, turn on debug mode (defaults to value of environment variable DIBSPACK_INSTALL_DEBUG and to off as a fallback).

  • --dibsignore/-f: string option, sets the name of the file where to take patterns for exclusions. It defaults to environment variable DIBSPACK_INSTALL_DIBSIGNORE and, as a fallback. to the string .dibsignore. There can be one such file inside each directory where you want to do pruning.

  • --dst/-d: string setting the destination of the copy. It defaults to the environment variable DIBSPACK_INSTALL_DST and, depending on the step parameter, to something else as a fallback (see below).

  • --preserve/-p: boolean option, when set it does not wipe the previous content of the destination directory. It defaults to the environment variable DIBSPACK_INSTALL_PRESERVE or to a false value as fallback.

  • --print/-P: boolean option, when set it does not copy anything but prints on standard output what will be copied. Defaults to environment variable DIBSPACK_INSTALL_PRINT or to a false value as fallback.

  • --src/-s: string setting the source of the copy. It defaults to the environment variable DIBSPACK_INSTALL_SRC and, depending to the step parameter, to something else as a fallback (see below).

The optional parameter step is a shorthand to set fallback defaults for the source and destination directories, namely:

  • if it takes value build, then the source eventually defaults to src_dir (i.e. the content of envile DIBS_DIR_SRC) and the destination to sub-directory app inside the cache directory (i.e. the second parameter).

  • if it takes value bundle', then the source eventuall defaults to sub-directory `app inside the cache directory (i.e. the content of envile DIBS_DIR_CACHE) and the destination defaults to /app.

  • any other value throws an exception.

The step can also be set via environment variable DIBSPACK_STEP.

The dibsignore file has the same format and follows the same rules as the more popular .gitignore file used by Git.

This program requires to run Perl inside the container. This should be a no-problem in the build steps, but might be trickier in the bundle steps. If this is actually the case, the suggestion is to prepare the copy with install/with-dibspack during the build step, then use install/simple-copy (which only relies on POSIX compliant /bin/sh) to place the artifacts in the right place during the bundle step.

perl/build

This dibspack aims at compiling Perl code. As a matter of fact, it only makes sure that prerequisites modules are properly installed, e.g. via cpanm or carton. It is invoked like this:

perl/build [work_dir]

When set, work_dir indicates that installations should be done "from within" the specific directory. To do this, work_dir is created as a symlink to src_dir (i.e. the content of envile DIBS_DIR_SRC) and then the rest of operations performed from there. If not set, it defaults to the environment variable DIBSPACK_PERL_APP or, as a fallback, the string /app.

The dibspack saves some configurations inside the target directory (work_dir/src_dir) in file .profile/10.perl-env.sh (directory .profile is the profile_dir). This is mainly aimed at setting the right paths for executing the shipped Perl programs.

Other environment variables can influence the dibspack execution:

  • DIBSPACK_VERBOSE, when set to 1 (exactly) turns on verbose mode.

  • DIBSPACK_SAVE_ENV can be set to a path where the environment is saved (both env and set). If the variable is defined but it does not start with a slash, then the environment is saved inside directory /.build_env.

  • DIBSPACK_SET_VERSION, when set to a non-empty string, triggers its saving inside the profile_dir inside file 20.version-env.sh.

  • CPANM_OPTS options passed to cpanm.

  • DIBSPACK_CPANM_VERBOSE sets verbose mode when running cpanm. Defaults to --quiet.

  • DIBSPACK_CPANM_TEST sets or disable testing of modules. Defaults to --notest.

The outcome of compilation is saved in the cache (i.e. the directory saved in envile DIBS_DIR_CACHE), inside sub-directory perl/local.

prereqs

This dibspack supports in the installation of OS-specific packages/prerequisites. It is invoked like this:

prereqs [--os OS] [-w|--workdir|--work-dir DIR] [step]

The source project is supposed to have a prereqs sub-directory, and have executable files like this inside:

prereqs/
    alpine.build
    alpine.bundle
    debian.build
    debian.bundle
    debian.some-other-step...

It works like this:

  • loads all enviles as environment variables;

  • it establishes the platform’s os based on command-line option --os, environment variable DIBS_OS, or looking at the ID inside /etc/os-release;

  • it establishes the work dir base on command-line option --workdir (or its aliases), on environment variable DIBS_WORK_DIR or, as a fallback, on the contents of envile DIBS_DIR_SRC;

  • it establishes a step name from the command line or from environment variable DIBS_PREREQS (leaving it blank by default);

  • it runs file $work_dir/prereqs/$os.$step if the step is defined, otherwise it run $work_dir/prereqs/$os.

procfile/add

This adds a simple handler for Procfile-like configurations support. This means that it’s possible to put a Procfile file inside the application directory, and it will hopefully honored (it also requires to set the associated program as the entry point of the generated container image).

This dibspack is controlled by environment variables (or enviles, all of them are loaded) with sensible defaults:

  • DIBSPACK_PROCFILE_DEFAULT: sets the default process to run, defaults to web.

  • DIBSPACK_PROCFILE_RUNNER: sets the name of the runner inside the container, defaults to /procfilerun.

  • DIBSPACK_PROCFILE_SPEC: sets the position of the Procfile file, defaults to /app/Procfile.

As anticipated, to use this dibspack effectively it is necessary to ensure that the dibs.yml configuration file sets the right entry point and command while saving the image, like this:

packs:
  foo:
    type:   git
    origin: https://github.com/polettix/dibspack-basic
actions:
  bundle:
    - from: 'some-image:latest'
    - name: add procfile
      pack: foo
      path: procfile/add
      commit:
        entrypoint: ['/procfilerun']
        cmd: []
    - tags: 'new-image:1.0'
    # ...

shellrun

This dibspack is a swiss-army knife that allows running multiple shell commands. It is invoked like this:

shellrun [command1 [command2 [...]]]

Each argument is a shell command that is run "plainly". For example, if the argument is echo ciao a tutti, then the following is executed:

echo ciao a tutti

and so on.

Example usage:

packs:
  foo:
    type:   git
    origin: https://github.com/polettix/dibspack-basic
actions:
  foobar:
    path:   shellrun
    args:
      - "printf '%s\n' 'whatever you want'"
      - 'ls -l /'
      # ...

For simplicity, all standard output is redirected to standard error, so that execution of command appears in the run log of dibs.

You can’t perform that action at this time.