paicku

Paicku is a wrapper of pack CLI for containerizing applications using buildpacks, in a little bit easier way which can also be called programmatically for testing locally your application.

Table of Contents

• Usage
  • Calling via CLI
  • Calling it Programmatically
    • Build and run an image
• Available commands
• Command Topics
  • Examples
• Contributing
  • Development
  • Run CLI in Development Mode
  • Run CLI in Production Mode
  • Testing

Usage

Calling via CLI

Install globally:

npm install -g paicku

Or use npx (no installation required):

cd ./my-node-app-dir
npx paicku build

The above command will output a container image to your registry with a random name.

Specify a custom image name and a path:

paicku build my-image-name --path /path/to/my/app/dir

Calling it Programmatically

All the commands that Paicku supports, can be called programmatically.

Build and run an image

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.build({
  imageName: 'my-app',
  path: './app',
  builder: 'docker.io/paketobuildpacks/builder-ubi8-base',
})

const container = await result.run({exposedPorts: 8080})

console.log(`Container started at ${container.getUrl()}`)

// Make a request
const response = await fetch(container.getUrl())
console.log('Response:', await response.text())

await container.stop()

Available commands

Command Topics

• paicku build - Build an image
• paicku builder - Display suggested builders for the given application
• paicku help - Display help for paicku.
• paicku inspect - Show information about a built app image
• paicku sbom - Interact with SBoM

Examples

Build with podman

paicku build my-app --container-runtime podman

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.build({
  imageName: 'my-app',
  'container-runtime': 'podman',
})

Build with a specific builder

paicku build my-image --builder docker.io/paketobuildpacks/builder-ubi8-base

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.build({
  imageName: 'my-image',
  builder: 'docker.io/paketobuildpacks/builder-ubi8-base',
})

Build from a remote Git repository

paicku build backend-image --path https://github.com/nodeshift/mern-workshop --context-dir backend

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.build({
  imageName: 'backend-image',
  path: 'https://github.com/nodeshift/mern-workshop:backend',
})

Build with environment variables

paicku build my-app --env BP_NODE_VERSION=18.*

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.build({
  imageName: 'my-app',
  env: ['BP_NODE_VERSION=18.*'],
})

Inspect a built image

paicku inspect my-image:latest

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.inspect('my-image:latest', {
  output: 'json',
})

console.log('Image information:', result.parsedStdout)

Get builder suggestions

paicku builder suggest

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.builder.suggest()

console.log('Suggested builders:', result.stdout)

Download SBOM

paicku sbom download my-image:latest --output-dir ./sbom

import {createPaicku} from 'paicku'

const paicku = createPaicku()

const result = await paicku.sbom.download('my-image:latest', {
  'output-dir': './sbom',
})

console.log('SBOM downloaded successfully')

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

Install the required Node.js modules:

npm install

Run CLI in Development Mode

Use the following command to run the CLI in development mode:

./bin/dev.js

Or to build an app:

./bin/dev.js build test/integration/testdata/nodejs_simple_app --container-runtime podman

Run CLI in Production Mode

To run the CLI in production mode, you need to build the application first:

npm run build

Then, execute the CLI:

./bin/run.js

Note: You must rebuild every time you make changes to the source code.

Testing

Run only the unit Tests

npm run test

Run Integration Tests Only

npm run integration:test:podman
npm run integration:test:docker

Run Tests in Debug Mode

For unit tests (useful for .only or extended execution time):

npm run unit:test:debug

Test Coverage

Run tests with coverage:

npm run test:report