Debify
Debify is a tool used for building and testing DAP appliance packages. It is mainly used to package and publish debian packages that are consumed into the appliance image in its build stage. However, it also packages and publishes an RPM package whenever it does so for a debian.
Installation
There are two different ways of installing debify: as a gem, or as a Docker image.
Installing the gem
Add this line to your application's Gemfile:
gem 'conjur-debify'
And then execute:
$ bundle
Or install it yourself as a ruby gem:
$ gem install conjur-debify
Installing the Docker image
Pull the Docker image:
$ VERSION=3.0.0
$ docker pull registry.tld/conjurinc/debify:$VERSION
Images are tagged with the version specified in VERSION
Use the config
subcommand to get a copy of the wrapper script and the secret definitions for publishing:
$ docker run --rm debify:$VERSION config script > docker-debify
$ chmod +x docker-debify
# Optionally, if publishing a deb
$ docker run --rm debify:$VERSION config secrets > publishing-secrets.yml
Running docker-debify
will then start a container configured to run debify:
$ ./docker-debify help
NAME
debify - Utility commands for building and testing Conjur appliance Debian packages
SYNOPSIS
debify [global options] command [command options] [arguments...]
VERSION
3.0.0
GLOBAL OPTIONS
--env=arg - Set an environment variable (e.g. TERM=xterm) when starting a container (may be used more than once, default:
none)
--help - Show this message
--[no-]local-bundle - Mount local bundle to reuse gems from previous installation
--version - Display the program version
COMMANDS
clean - Clean current working directory of non-Git-managed files
config - Show the given configuration
detect-version - Auto-detect and print the repository version
help - Shows a list of commands or help for one command
initconfig - Initialize the config file using current global options
package - Build a debian package for a project
publish - Publish a debian package to apt repository
sandbox - Setup a development sandbox for a Conjur debian package in a Conjur appliance container
test - Test a Conjur debian package in a Conjur appliance container
Note that debify itself creates images and starts containers, so it
needs access to the host's docker.sock
. Additionally, it requires
that it be started in root directory of the project being packaged.
Build a package
Builds a Conjur Debian package from a Ruby gem.
$ debify help package
NAME
package - Build a debian package for a project
SYNOPSIS
debify [global options] package [command options] project_name -- <fpm-arguments>
b
DESCRIPTION
The package is built using fpm (https://github.com/jordansissel/fpm).
The project directory is required to contain:
* A Gemfile and Gemfile.lock * A shell script called debify.sh
debify.sh is invoked by the package build process to create any custom files, other than the project source tree. For example, config files can be
created in /opt/conjur/etc.
The distrib folder in the project source tree is intended to create scripts for package pre-install, post-install etc. The distrib folder is not
included in the deb package, so its contents should be copied to the file system or packaged using fpm arguments.
All arguments to this command which follow the double-dash are propagated to the fpm command.
COMMAND OPTIONS
-a, --architecture=arg - Set the architecture of the package; can be set to arm64 or amd64 (default: amd64)
--additional-files=arg - Specify files to add to the FPM image that are not included from the git repo (default: none)
-d, --dir=arg - Set the current working directory (default: none)
--dockerfile=arg - Specify a custom Dockerfile.fpm (default: none)
-i, --image=arg - Image name (default: cyberark/ubuntu-ruby-builder)
-o, --output=arg - Set the output file type of the fpm command (e.g rpm) (default: none)
-t, --image-tag=arg - Image tag, e.g. 4.5-stable, 4.6-stable (default: latest)
-v, --version=arg - Specify the deb version; by default, it's read from the VERSION file (default: none)
Example usage
$ package_name=$(debify package -d example -v 0.0.1 example -- --post-install /distrib/postinstall.sh)
$ echo $package_name
conjur-example_0.0.1_amd64.deb
Test a package
$ debify help test
NAME
test - Test a Conjur debian package in a Conjur appliance container
SYNOPSIS
debify [global options] test [command options] project-name test-script
DESCRIPTION
First, a Conjur appliance container is created and started. By default, the container image is registry.tld/conjur-appliance-cuke-master. An image tag
MUST be supplied. This image is configured with all the CONJUR_ environment variables setup for the local environment (appliance URL, cert path, admin
username and password, etc). The project source tree is also mounted into the container, at /src/<project-name>.
This command then waits for Conjur to initialize and be healthy. It proceeds by installing the conjur-<project-name>_latest_amd64.deb from the project
working directory.
Then the evoke "test-install" command is used to install the test code in the /src/<project-name>. Basically, the development bundle is installed and
the database configuration (if any) is setup.
Next, an optional "configure-script" from the project source tree is run, with the container id as the program argument. This command waits for Conjur
to be healthy again.
Finally, a test script from the project source tree is run, again with the container id as the program argument.
Then the Conjur container is deleted (use --keep to leave it running).
COMMAND OPTIONS
-c, --configure-script=arg - Shell script to configure the appliance before testing (default: none)
-d, --dir=arg - Set the current working directory (default: none)
-i, --image=arg - Image name (default: registry.tld/conjur-appliance-cuke-master)
-k, --[no-]keep - Keep the Conjur appliance container after the command finishes
--[no-]pull - Pull the image, even if it's in the Docker engine already (default: enabled)
-t, --image-tag=arg - Image tag, e.g. 4.5-stable, 4.6-stable (default: none)
Example usage
$ debify test -i conjur-appliance-cuke-master --image-tag 4.6-dev --no-pull -d example example test.sh
Publish a package
$ debify help publish
NAME
publish - Publish a debian package to apt repository
SYNOPSIS
debify [global options] publish [command options] distribution project-name
DESCRIPTION
Publishes a deb created with `debify package` to our private apt repository.
"distribution" should match the major/minor version of the Conjur appliance you want to install to.
The package name is a required option. The package version can be specified as a CLI option, or it will be auto-detected from Git.
--component should be 'stable' if run after package tests pass or 'testing' if the package is not yet ready for release. If you don't specify the component, it will be set to
'testing' unless the current git branch is 'master' or 'origin/master'. The git branch is first detected from the env var GIT_BRANCH, and then by checking `git rev-parse
--abbrev-ref HEAD` (which won't give you the answer you want when detached).
COMMAND OPTIONS
-c, --component=arg - Maturity stage of the package, 'testing' or 'stable' (default: none)
-d, --dir=arg - Set the current working directory (default: none)
-v, --version=arg - Specify the deb package version; by default, it's computed automatically (default: none)
Example usage
You will need read permission for the ci/artifactory/users/jenkins/username
and ci/artifactory/users/jenkins/password
variables in order to run this command from your local machine.
$ debify publish -c stable 0.0.1 example
[Thread 0] Uploading artifact: https://conjurinc.artifactoryonline.com/conjurinc/debian-local/conjur-example_0.1.1-c9fd618_amd64.deb;deb.distribution=0.1.1;deb.component=possum;deb.architecture=amd64
[Thread 0] Artifactory response: 201 Created
Uploaded 1 artifacts to Artifactory.
Create a development session in a Conjur appliance container
$ debify help sandbox
NAME
sandbox - Setup a development sandbox for a Conjur debian package in a Conjur appliance container
SYNOPSIS
debify [global options] sandbox [command options]
DESCRIPTION
First, a Conjur appliance container is created and started. By default, the container image is
registry.tld/conjur-appliance-cuke-master. An image tag MUST be supplied. This image
is configured with all the CONJUR_ environment variables setup for the local environment (appliance URL,
cert path, admin username and password, etc). The project source tree is
also mounted into the container, at /src/<project-name>, where <project-name> is taken from the name of the
current working directory.
Once in the container, use "/opt/conjur/evoke/bin/dev-install" to install the development bundle of your project.
COMMAND OPTIONS
--bind=arg - Bind another source directory into the container. Use <src>:<dest>, where both are full paths. (default: none)
-d, --dir=arg - Set the current working directory (default: none)
-i, --image=arg - Image name (default: registry.tld/conjur-appliance-cuke-master)
--[no-]pull - 'docker pull' the Conjur container image
-t, --image-tag=arg - Image tag, e.g. 4.5-stable, 4.6-stable (default: none)
Example usage
authz $ debify sandbox -t $(cat VERSION_APPLIANCE)-stable
... much logging
authz $ docker exec -it authz-sandbox bash
root@7d4217655332:/src/authz# /opt/conjur/evoke/bin/dev-install authz
...
root@7d4217655332:/src/authz# export RAILS_ENV=test
root@7d4217655332:/src/authz# bundle exec rake db:migrate
Usage with docker-compose
As of v1.10.0, both the test
and sandbox
subcommands support the --net
switch.
This allows you to specify a network to which the Conjur appliance container should be attached.
There are a variety of ways to make use of this feature. One possibility is creating a network
using docker network create
, then attaching both the docker-compose services, as well, as the Conjur
appliance container created by debify, to it.
As a (somewhat contrived) example, create a new docker network:
$ docker network create testnet
Use a docker-compose file like example/docker-compose.yml
version: "2"
networks:
svcnet:
external:
name: testnet
services:
db:
image: postgres
container_name: mydb
networks:
- svcnet
Bring up the db service:
debify $ cd example
example $ docker-compose up -d
Start a sandbox, see that it can resolve the hostname mydb
:
example $ debify sandbox -t 5.0-stable --net testnet
example $ docker exec -it example-sandbox /bin/bash
root@7d4217655332:/src/example# getent hosts mydb
172.19.0.2 mydb
Contributing
For instructions on how to get started and descriptions of our development workflows, please see our contributing guide.