The “multiple operating systems” part refers to the output<\/em> package types. You’ll typically run FPM on a single build host (e.g., a Linux machine, or even a Docker container) to generate packages for Debian\/Ubuntu, RedHat\/CentOS, Arch Linux, etc.<\/p>\n Here’s a comprehensive guide on how to use FPM effectively.<\/p>\n —<\/p>\n * Simplicity:<\/strong> Drastically simplifies the process of creating 1. Ruby:<\/strong> FPM is a Ruby gem, so you need Ruby installed. 2. RubyGems:<\/strong> Ruby’s package manager, usually installed with Ruby.<\/p>\n Once Ruby is set up, install FPM:<\/p>\n (You might need FPM’s command structure is generally:<\/p>\n Let’s say you have a simple application structure:<\/p>\n And And ### 1. Preparing Your Files (Staging Directory)<\/p>\n It’s best practice to organize your files in a “staging” directory that mirrors the final installation path within<\/em> the target system.<\/p>\n Now, ### 2. Creating a Debian (.deb) Package<\/p>\n This will output a file like To install and test:<\/p>\n ### 3. Creating a RedHat\/CentOS (.rpm) Package<\/p>\n Using the exact same staging directory<\/em> and almost the same command:<\/p>\n * This will output a file like To install and test:<\/p>\n (Note: ### 4. Adding Pre\/Post-Install Scripts<\/p>\n You can execute scripts at various stages of the package lifecycle.<\/p>\n Create script files (e.g., Now, add them to your FPM command:<\/p>\n ### 5. Packaging a Python Application<\/p>\n If you have a Python project with a * Alternative (and often more robust) for Python apps:<\/strong> 2. Then package the staging directory using This approach gives you more control over the final file layout.<\/p>\n ### 6. Marking Configuration Files<\/p>\n For files that users might modify (like * * Use a Staging Directory ( * What is FPM and Why Use It?<\/h3>\n
.deb<\/code> or .rpm<\/code> packages, which can otherwise be quite complex with dpkg-buildpackage<\/code> or rpmbuild<\/code>.
\n* Speed:<\/strong> Create a package in minutes, not hours.
\n* Flexibility:<\/strong> Package almost anything: a directory of files, a Python application, a Ruby gem, a pre-built binary, etc.
\n* Cross-Platform Output:<\/strong> Generate packages for Debian, Ubuntu, CentOS, RHEL, Fedora, Arch Linux, Solaris, macOS, and more, all from one command.
\n* Automation:<\/strong> Easily integrate into CI\/CD pipelines.<\/p>\nPrerequisites<\/h3>\n
\n * On Debian\/Ubuntu: sudo apt update && sudo apt install ruby ruby-dev build-essential<\/code>
\n * On CentOS\/RHEL: sudo yum install ruby ruby-devel @development<\/code> (or dnf<\/code> for newer versions)
\n * On macOS: Ruby is usually pre-installed, but it’s recommended to use a version manager like rbenv<\/code> or rvm<\/code>.<\/p>\nInstallation<\/h3>\n
sudo gem install fpm<\/code><\/pre>\nsudo<\/code> depending on your Ruby installation. If you’re using rbenv<\/code> or rvm<\/code>, you likely won’t need sudo<\/code>.)<\/em><\/p>\nCore Concepts and Essential Flags<\/h3>\n
fpm -s -s
\n * dir<\/code>: (Most common) Package files from a directory.
\n * gem<\/code>: Package a Ruby gem.
\n * python<\/code>: Package a Python application (requires setuptools<\/code>).
\n * rpm<\/code>: Convert an RPM to another format.
\n * deb<\/code>: Convert a DEB to another format.
\n * cpan<\/code>: Package a Perl module.
\n * npm<\/code>: Package a Node.js module.
\n * tar<\/code>: Package a tarball.
\n * … and more.
\n* -t
\n * deb<\/code>: Debian\/Ubuntu package.
\n * rpm<\/code>: RedHat\/CentOS\/Fedora package.
\n * tar<\/code>: Generic tarball.
\n * zip<\/code>: Generic zip archive.
\n * pkg<\/code>: macOS package.
\n * pacman<\/code>: Arch Linux package.
\n * msi<\/code>: (Experimental) Windows Installer package.
\n * … and more.
\n* -n my-custom-app<\/code>).
\n* -v 1.0.0<\/code>).
\n* -p
\n* -d \"-d \"nginx\"<\/code> or -d \"python3 >= 3.6\"<\/code>). You can specify multiple -d<\/code> flags.
\n* --description \"
\n* --url \"
\n* --license \"MIT<\/code>, GPLv3<\/code>).
\n* --maintainer \"
\n* --architecture amd64<\/code>, x86_64<\/code>, all<\/code>, noarch<\/code>).
\n* --iteration 1<\/code>, 2.el7<\/code>). Useful for distinguishing package builds of the same software version.
\n* --prefix \/opt\/my-app<\/code>). Defaults to \/<\/code> for dir<\/code> source.
\n* -C --chdir
\n* --input-type<\/code> and --output-type<\/code>:<\/strong> Aliases for -s<\/code> and -t<\/code>.<\/p>\nStep-by-Step Examples<\/h3>\n
my-app-src\/\n\u251c\u2500\u2500 bin\/\n\u2502 \u2514\u2500\u2500 myapp.sh\n\u251c\u2500\u2500 etc\/\n\u2502 \u2514\u2500\u2500 myapp.conf\n\u2514\u2500\u2500 lib\/\n \u2514\u2500\u2500 myapp.py<\/code><\/pre>\nmyapp.sh<\/code> looks like this:<\/p>\n#!\/bin\/bash\necho \"Hello from My App v1.0.0!\"\ncat \/etc\/myapp\/myapp.conf<\/code><\/pre>\nmyapp.conf<\/code>:<\/p>\nAPP_SETTING=\"default_value\"<\/code><\/pre>\nmkdir -p \/tmp\/my-app-staging\/opt\/myapp\/bin\nmkdir -p \/tmp\/my-app-staging\/etc\/myapp\n\ncp my-app-src\/bin\/myapp.sh \/tmp\/my-app-staging\/opt\/myapp\/bin\/\ncp my-app-src\/etc\/myapp.conf \/tmp\/my-app-staging\/etc\/myapp\/\ncp my-app-src\/lib\/myapp.py \/tmp\/my-app-staging\/opt\/myapp\/lib\/<\/code><\/pre>\n\/tmp\/my-app-staging<\/code> looks like this:<\/p>\n\/tmp\/my-app-staging\/\n\u251c\u2500\u2500 etc\/\n\u2502 \u2514\u2500\u2500 myapp\/\n\u2502 \u2514\u2500\u2500 myapp.conf\n\u2514\u2500\u2500 opt\/\n \u2514\u2500\u2500 myapp\/\n \u251c\u2500\u2500 bin\/\n \u2502 \u2514\u2500\u2500 myapp.sh\n \u2514\u2500\u2500 lib\/\n \u2514\u2500\u2500 myapp.py<\/code><\/pre>\nfpm -s dir -t deb \\\n -n \"my-custom-app\" \\\n -v \"1.0.0\" \\\n --iteration \"1\" \\\n --architecture \"amd64\" \\\n --description \"A simple custom application.\" \\\n --url \"https:\/\/example.com\/my-app\" \\\n --license \"MIT\" \\\n --maintainer \"Your Name -C \/tmp\/my-app-staging\/<\/code>: Tells FPM to change into this directory <\/em>before* packaging.
\n* .<\/code>: This tells FPM to package everything in the current directory (which is now \/tmp\/my-app-staging<\/code> due to -C<\/code>).<\/p>\nmy-custom-app_1.0.0-1_amd64.deb<\/code>.<\/p>\nsudo dpkg -i my-custom-app_1.0.0-1_amd64.deb\n\/opt\/myapp\/bin\/myapp.sh<\/code><\/pre>\nfpm -s dir -t rpm \\\n -n \"my-custom-app\" \\\n -v \"1.0.0\" \\\n --iteration \"1.el7\" \\\n --architecture \"x86_64\" \\\n --description \"A simple custom application.\" \\\n --url \"https:\/\/example.com\/my-app\" \\\n --license \"MIT\" \\\n --maintainer \"Your Name --iteration \"1.el7\"<\/code>: A common convention for RPMs indicating the release number and the target OS (Enterprise Linux 7).
\n* --architecture \"x86_64\"<\/code>: Standard for 64-bit RPMs.<\/p>\nmy-custom-app-1.0.0-1.el7.x86_64.rpm<\/code>.<\/p>\nsudo yum install my-custom-app-1.0.0-1.el7.x86_64.rpm\n\/opt\/myapp\/bin\/myapp.sh<\/code><\/pre>\nyum<\/code> or dnf<\/code> will handle dependencies automatically if they are in configured repositories.)<\/em><\/p>\npreinstall.sh<\/code>, postinstall.sh<\/code>):<\/p>\npreinstall.sh<\/code>:<\/strong><\/p>\n#!\/bin\/bash\necho \"Running pre-install script for my-custom-app...\"\nExample: Check for a condition before installation<\/h2>\nif [ -f \/opt\/myapp\/bin\/myapp.sh ]; then\n echo \"My App already exists, upgrading.\"\nelse\n echo \"Installing My App for the first time.\"\nfi\nexit 0<\/code><\/pre>\n
postinstall.sh<\/code>:<\/strong><\/p>\n#!\/bin\/bash\necho \"Running post-install script for my-custom-app...\"\nExample: Create a symlink or start a service<\/h2>\nif [ ! -f \/usr\/local\/bin\/myapp ]; then\n sudo ln -s \/opt\/myapp\/bin\/myapp.sh \/usr\/local\/bin\/myapp\n echo \"Created symlink \/usr\/local\/bin\/myapp\"\nfi\necho \"Installation complete!\"\nexit 0<\/code><\/pre>\n
fpm -s dir -t deb \\\n -n \"my-custom-app\" -v \"1.0.0\" --iteration \"1\" --architecture \"amd64\" \\\n --description \"A simple custom application with scripts.\" \\\n --url \"https:\/\/example.com\/my-app\" --license \"MIT\" \\\n --maintainer \"Your Name --before-install
\n --after-install
\n* Other options: --before-remove<\/code>, --after-remove<\/code>, --before-upgrade<\/code>, --after-upgrade<\/code>.<\/p>\nsetup.py<\/code> or pyproject.toml<\/code>:<\/p>\n# In your python_app_root_dir\/\nfpm -s python -t deb \\\n -n \"my-python-app\" \\\n -v \"0.5.0\" \\\n --iteration \"1\" \\\n --architecture \"all\" \\\n --description \"A Python application packaged by FPM.\" \\\n --python-bin \/usr\/bin\/python3 \\\n --python-pip \/usr\/bin\/pip3 \\\n . # Packages the current directory as a Python source<\/code><\/pre>\n--python-bin<\/code> and --python-pip<\/code>: Specify the Python executable and pip to use for building.
\n* --architecture \"all\"<\/code>: Often appropriate for pure Python apps.<\/p>\n
\n1. Install your Python app into a staging directory:<\/p>\nmkdir -p \/tmp\/python-staging\n pip install . --prefix=\/usr\/local --root=\/tmp\/python-staging<\/code><\/pre>\nfpm -s dir<\/code>:<\/p>\nfpm -s dir -t deb \\\n -n \"my-python-app\" -v \"0.5.0\" --iteration \"1\" --architecture \"all\" \\\n --description \"A Python application via dir source.\" \\\n -d \"python3\" \\\n -C \/tmp\/python-staging\/ \\\n .<\/code><\/pre>\nmyapp.conf<\/code>), you want the package manager to handle upgrades gracefully (e.g., prompt to merge changes or preserve the user’s version).<\/p>\nfpm -s dir -t deb \\\n -n \"my-custom-app\" -v \"1.0.0\" --iteration \"1\" --architecture \"amd64\" \\\n --description \"App with a config file.\" \\\n --url \"https:\/\/example.com\/my-app\" --license \"MIT\" \\\n --maintainer \"Your Name --config-files Best Practices and Advanced Tips<\/h3>\n
-C<\/code>):<\/strong> Always build your package contents in a temporary directory (\/tmp\/my-app-staging<\/code> in our example) that directly reflects the final installation path. This makes your FPM commands cleaner and less error-prone.
\n* Version Control:<\/strong> Keep your my-app-src<\/code> and any build scripts under version control.
\n* Automation:<\/strong> Integrate FPM into your build scripts (e.g., Makefile<\/code>, Rakefile<\/code>, shell scripts) or CI\/CD pipeline (Jenkins, GitLab CI, GitHub Actions) to automate package creation on every release or commit.
\n* Docker for Build Consistency:<\/strong> To ensure your packages are built consistently and don’t pick up host-specific dependencies, use Docker.<\/p>\n# Dockerfile for building packages\n FROM ruby:3.1-slim-buster\n RUN apt-get update && apt-get install -y build-essential\n RUN gem install fpm\n WORKDIR \/build\n COPY . \/build\n # Now run your fpm command inside the container\n CMD [\"fpm\", \"-s\", \"dir\", \"-t\", \"deb\", \"-n\", \"my-custom-app\", ...]<\/code><\/pre>\n--prefix<\/code>:<\/strong> If you want all your files to be installed under a specific directory (e.g., \/opt\/your-company\/my-app<\/code>), use --prefix \/opt\/your-company\/my-app<\/code> and then fpm -C \/tmp\/my-app-staging\/opt\/your-company\/my-app .<\/code>.
\n --exclude<\/code>:<\/strong> For dir<\/code> sources, you can exclude files or directories using --exclude \".git\" --exclude \"<\/em>.log\"<\/code>.
\n* Signing Packages:<\/strong> For production environments, you’ll want to sign your .deb<\/code> and .rpm<\/code> packages for security and integrity verification. FPM itself doesn’t directly sign, but you can integrate dpkg-sig<\/code> or rpmsign<\/code> into your post-FPM build steps.
\n* Complex Dependencies:<\/strong> For very complex dependency scenarios, you might still need to consult the native packaging tools’ documentation (dpkg<\/code> or rpm<\/code>). FPM handles most common cases well.
\n* Debugging:<\/strong> If your package isn’t working as expected, examine its contents:
\n * For .deb<\/code>: dpkg -c package.deb<\/code> (list contents), dpkg -I package.deb<\/code> (show info).
\n * For .rpm<\/code>: rpm -qpl package.rpm<\/code> (list contents), rpm -qpi package.rpm<\/code> (show info).<\/p>\n