Docs menu
Customizing the build
How to shape the Ruby build on Primcloud: rake tasks, custom install steps, native gem dependencies, and Debian packages via project.toml.
On this page
Most Ruby apps deploy on Primcloud with no custom build steps. The build runs bundle install, then rake assets:precompile if the task exists, and that's it. When you need more, you have three extension points: your own rake tasks, BUNDLE_* environment variables, and Debian package installs for OS-level libraries.
Build hooks#
The Ruby build does not run arbitrary shell scripts. Custom build-time work goes through rake tasks that hook into or supplement the tasks the build already invokes.
Enhance assets:precompile. Add extra work to the asset pipeline by defining a rake task with enhance:
namespace :assets do
task :postbuild do
# Generate a build stamp, warm a cache, etc.
File.write("public/BUILD_SHA", ENV.fetch("BUILD_SHA", "unknown"))
end
end
Rake::Task["assets:precompile"].enhance do
Rake::Task["assets:postbuild"].invoke
end
Rake runs the enhancement after assets:precompile completes. Because rake assets:precompile runs automatically on every Rails deploy, no extra config is needed to trigger it.
Non-Rails apps. If your app isn't Rails and doesn't already run rake at build time, you can add a Rakefile at the root, include rake in your Gemfile.lock, and define whatever tasks you need, but the build won't invoke them unless they're chained into assets:precompile. For non-Rails builds where you need a hook, the cleaner path is to move the work into your Procfile command's startup (release-time work) or into an on_worker_boot callback if you're on Puma.
Custom install steps#
To adjust bundle install's behavior, set Bundler configuration via BUNDLE_* environment variables under Settings → Secrets. Common changes:
BUNDLE_WITHOUT: override the defaultdevelopment:testexclusion.BUNDLE_WITHOUT=development:test:docskips docs too.BUNDLE_JOBS: increase to parallelize gem downloads.BUNDLE_JOBS=4is a reasonable ceiling.BUNDLE_RETRY: number of times to retry a failed gem download. Defaults to Bundler's own default.
The rest of Bundler's config surface is available via the same BUNDLE_* pattern; see Bundler's config reference.
What you cannot change: BUNDLE_FROZEN is set by the build, and setting it yourself has no effect.
Environment available to rake tasks. All environment variables set under Settings → Secrets are present when rake runs. Read them with ENV.fetch("KEY") in your Rakefile.
Native dependencies#
Two categories of "native" your Ruby app can rely on:
Native gems with bundled binaries. Gems like nokogiri, bcrypt, sqlite3, pg, and sassc build C extensions at install time or (increasingly) ship precompiled binaries per Ruby version and platform. They install with bundle install, using a precompiled Linux binary when the gem has one.
System libraries your code or a native gem links against, like libxml2, libpq, libmariadb, or libvips, come from system packages, below.
Debian packages#
When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:
[_]
schema-version = "0.2"
[com.heroku.buildpacks.deb-packages]
install = [
"libvips",
"libpq-dev",
"poppler-utils",
]
Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.
Advanced options (rarely needed):
- Skip a package's dependencies:
{ name = "some-package", skip_dependencies = true } - Force a reinstall:
{ name = "some-package", force = true } - Install from a URL:
download = ["https://example.com/package-1.2.3.deb"] - Add a package repository: a
[[com.heroku.buildpacks.deb-packages.sources]]table withuri,suites,components,arch, andsigned_by(the repository's key as an ASCII-armored PGP block).
Note
The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.