puppi

Overview

Puppi: A Pluggable Deploy Automation and SysAdmin helper Puppet module

Detected project type: Puppet.

This repository was migrated from upstream source github.com/shafiqalibhai/puppi and is preserved here for archival, reference, or continued local development.

At a glance

• Default branch: master
• Visibility: public
• Size: 107 KB
• Created: 2026-04-27
• Last updated: 2026-04-27
• Stars / Forks / Open issues: 0 / 0 / 0

Languages

Language	Bytes	Share
Puppet	124,822 bytes	67.6%
Shell	35,645 bytes	19.3%
HTML	24,163 bytes	13.1%

Repository structure

• files/
• manifests/
• templates/
• Modulefile (245 B)
• README (8,635 B)
• README.check (2,037 B)
• README.deploy (13,575 B)
• README.info (2,420 B)
• README.log (1,227 B)

Getting started

Clone the repository:

git clone https://forgejo.deployview.com/ssa/puppi.git
cd puppi

Installation

git clone https://forgejo.deployview.com/ssa/puppi.git
cd puppi

Usage

Refer to the source files in this repository for entry points and intended usage. Update this section with concrete examples once they are established.

Original README

The content below is preserved from the previous README. Headings have been demoted so they don't compete with the new top-level sections.

Puppi: A Pluggable Deploy Automation and SysAdmin helper Puppet module

Written by Alessandro Franceschi / al @ lab42.it

Source: http://www.example42.com

Licence: Apache 2

Puppi is a Puppet module that lets sysadmins standardize, manage and automate the deployment of web applications and provides quick and standard commands to obtain informations about the system and what's is going on it. Its structure provides FULL flexibility on the actions required for virtually any kind of application deployment and information gathering. The module provides:

• The puppi command and its whole working environment
• A set of scripts that can be used in chain to automate any kind of deployment
• Puppet defines that make it easy to prepare a puppi set of commands for a project deployment
• Puppet defines to populate the output of the different actions

USAGE OF THE PUPPI COMMAND puppi <project_name> [ -options ] The puppi command has these possibile actions:

• puppi init <project_name> : First time initialization of the defined project
• puppi deploy <project_name> : Deploys the defined project
• puppi rollback <project_name> [state] : Rollback to a previous deploy state
• puppi check [project_name] : Runs project specific and host wide checks
• puppi log [project_name] : Tails system wide or project specific logs
• puppi info [topic] : Show system information (for all or only the specified topic)
• puppi todo [topic] : Show things to do (or done) manually on the system The deploy/rollback/init actions puppi run the commands in /etc/puppi/projects/$project_name/$action, log their status and then run the commands in /etc/puppi/projects/$project_name/report to provide reporting, in whatever, pluggable, way. You can also provide some options: -f : Force puppi commands execution also on CRITICAL errors -i : Interactively ask confirmation for every command -t : Test mode. Just show the commands that should be executed without doing anything -d <yes|full>: Debug mode. Show debugging info during execution -o "parameter=value parameter2=value2" : Set manual options to override defaults. The options must be in parameter=value syntax, separated by spaces and inside double quotes.

Some usage examples: puppi check : Run host-wide checks. puppi log : Show system logs puppi info : Show general system infos (outputs all the topics available) puppi deploy myapp : Deploys myapp according to the logic defined in Puppet manifests

THE PUPPI MODULE The set of commands needed for each of these actions s entirely managed with specific Puppet "basic defines": puppi::project - Creates the main project structure. One or more different deployment projects can exist on a node. puppi::initialize - Creates a single command to be placed in the init sequence. It's not required for every project. puppi::deploy - Creates a single command to be placed in the deploy sequence. More than one is generally needed for each project. puppi::rollback - Creates a single command to be placed in the rollback sequence. More than one is generally needed for each project. puppi::check - Creates a single check (based on Nagios plugins) for a project or for the whole host (host wide checks are auto generated by Example42 monitor module) puppi::report - Creates a reporting command to be placed in the report sequence. puppi::log - Creates a log filename entry for a project or the whole hosts. puppi::info - Creates an info entry with the commands used to provide info on a topic

Read details in the relevant READMEs

FILE PATHS (all of them are provided, and can be configured, in the puppi module): /usr/sbin/puppi - Where the puppi command is placed. Currently is a bash script. /etc/puppi/puppi.conf - Puppi main config file. Here various puppi wide paths are defined /etc/puppi/checks/ - $checksdir - Here can be placed all the host wide checks. If you use the Example42 monitor module and have "puppi" as $monitor_tool, this directory is automatically filled with Nagios plugins based checks. /etc/puppi/projects/ - $projectsdir - In this directory you can have one or more projects subdirs, with the commands to be run for deploy, rollback and check actions. They are completely built (and purged) by the Puppet module. /etc/puppi/scripts/ - $scriptsdir - The general-use scripts directory, these are used by the above commands and may require one or more arguments. /etc/puppi/logs/ - $logssdir - The general-use directory where are placed files containing the log paths to be used by puppi log /etc/puppi/info/ - $infodir - The directory where are placed files containing the commands used by puppi info /var/lib/puppi/archive/ - $archivedir - Where all data to rollback is placed. /var/lib/puppi/archive/ - $archivedir - Where all data to rollback is placed. /var/log/puppi/ - $logdir - Where logs and reports of the different commands are placed. /tmp/puppi/ - $workdir - Temporary, scratchable, directory where Puppi places temporary files. /tmp/puppi/$project/config - A runtime configuration file, where are dinamically placed variables usable by all the scripts invoked by puppi. This is necessary to mantain "state" information that changes on every puppi run (such as the deploy datetime, used for backups).

HOW TO CUSTOMIZE It should be clear that with puppi you have full flexibility in the definition of a deployment procedure, since the puppi command is basically a wrapper that executes arbitrary scripts with a given sequence, in pure KISS logic. The advantanges though, are various:

• You have a common syntax to manage deploys and rollbacks on an host
• In your Puppet manifests you can set in simple, coherent and still flexible and customizable defines all the elements you need for your application deployments. Think about it: with just a Puppet define you build the whole deploy logic
• Reporting for each deploy/rollback is built-in and extensible
• Automatic checks can be built in the deploy procedure
• You have a common, growing, set of general-use scripts for typical actions
• You have quick and useful command to see what's happening on the system (puppi check, log, info)

There are different parts where you can customize the behaviour of puppi:

• The set of general-use scripts in /etc/puppi/scripts/ ( this dir is filled with the content of puppi/files/scripts/ ) can/should be enhanced. These can be arbitrary scripts in whatever language. If you want to follow puppi's logic, though, consider that they should import the common and runtime configuration files and have an exit code logic similar to the one of Nagios plugins: 0 is OK, 1 is WARNING, 2 is CRITICAL. Note that by default a script that exits with WARNING doesn't block the deploy procedure, on the other hand, if a script exits with CRITICAL (exit 2) by default it blocks the procedure. Take a second, also, to explore the runtime config file created by the puppi command that contains variables that can be set and used by the scripts invoked by puppi.
• The custom project defines that describe deploy templates. These are placed in puppi/manifests/project/ and can request all the arguments you want to feed your scripts with. Generally is a good idea to design a standard enough template that can be used for all the cases where the deployment procedure involves similar steps. Consider also that you can handle exceptions with variables (see the $loadbalancer_ip usage in puppi/manifests/project/maven.pp)

DEPENDENCIES The Example42 puppi module aims to be independent and easily droppable in your set of modules. In order to do something useful by default it need some packages that you probably already manage:

• nagios plugins for the puppi check,
• curl for some general scripts used in puppi deploy.

Extra elements for check, info and log are automatic included with the relevant application if you use the Example42 modules.

PROJECT STATUS Puppi is a work in progress. It has been originally designed to automate deployments in a specific environment and more project templates have to be written to manage different scenarios. It has evolved with some commands useful to quickly understand what's happening on the system and how it's configured. It has greatly broadened its applications and possibilities with the introduction of the mc-puppi mcollective command and the relevant plugin. All the puppi commands you can issue to obtain information, check status and manage applications deployments are now usable via Mcollective.

Contributing

Contributions are welcome. The typical workflow is:

1. Open an issue describing the change you'd like to make.
2. Fork the repository (or create a feature branch if you have write access).
3. Commit your changes with clear, descriptive messages.
4. Open a pull request against the master branch.

Please follow the existing code style and include tests or reproduction steps where relevant.

License

No LICENSE file is currently present in this repository. Treat the contents as all rights reserved by the author until an explicit license is added. If you intend to share or accept contributions, consider adding an OSI-approved license such as MIT, Apache-2.0, or GPL-3.0.

Repository

• Browse: https://forgejo.deployview.com/ssa/puppi
• Clone (HTTPS): https://forgejo.deployview.com/ssa/puppi.git
• Clone (SSH): ssh://git@forgejo.deployview.com:30143/ssa/puppi.git
• Upstream / origin: github.com/shafiqalibhai/puppi

---

This README was generated automatically based on repository metadata, contents, and any prior README content. Edit any section above to add project-specific detail.