Understanding Tebako Packaging Scenarios for Ruby Applications

Maxim Samsonov on 27 Mar 2025

Tebako Packaging Scenarios

General

Tebako is an advanced executable packager designed for applications written in interpreted languages. It simplifies distribution and deployment by packaging an entire project—including its runtime—into a single, high-performance executable binary.

Packaging Scenarios for Ruby Applications

There are two common methods for distributing a Ruby application:

Copying the entire directory tree of the application to the target system.
Creating a Ruby gem from the application and publishing or distributing it as a gem.

Tebako supports both methods, but with an important distinction: during packaging, it does not deploy the application to the target system. Instead, it places it in a pristine Ruby environment that functions as an in-memory filesystem ("memfs").

Regardless of the packaging scenario, Tebako requires two inputs:

A root folder containing the application to be packaged.
An entry point—a Ruby file that will be executed when the packaged application starts.

The appropriate packaging scenario is determined by the contents of the root folder:

1. Simple Script

If the root folder does not contain a Gemfile, .gemspec, or .gem files, Tebako treats the application as a simple script.

In this case:

The entire root folder (including subdirectories) is copied to <memfs root>/local.
On startup, Tebako executes <memfs root>/local/<entry point>.

2. Bundled Project

If the root folder contains a Gemfile but no .gemspec files, the application is considered a bundled project. This is common for Rails or Sinatra projects.

In this scenario, Tebako:

Runs bundle install using the provided Gemfile within the pristine Ruby environment.
Copies the root folder and all subdirectories to <memfs root>/local.
Executes <memfs root>/local/<entry point> on startup.

3. Gem Packaging

If the root folder contains a .gemspec file but no Gemfile, Tebako assumes it is packaging a gem.

In this case:

Tebako runs the following commands within the pristine Ruby environment:

gem build
gem install

The entry point is assumed to be one of the gem’s executables, placed in the binary folder during installation. Within Tebako’s in-memory filesystem, this folder is <memfs root>/bin.
On startup, Tebako executes <memfs root>/bin/<entry point>.

Note	Multiple `.gemspec` files in the root folder are not supported.

4. Bundled Gem

If the root folder contains both a .gemspec file and a Gemfile, Tebako assumes it is packaging a bundled gem.

In this case:

Tebako runs the following commands within the pristine Ruby environment:

bundle install
bundle exec gem build
bundle exec gem install

The entry point follows the same logic as in the Gem Packaging scenario (<memfs root>/bin/<entry point>).

Note	Multiple `.gemspec` files in the root folder are not supported.

5. Prebuilt Gems

If the root folder contains .gem files but no Gemfile or .gemspec, Tebako assumes it is packaging prebuilt gems.

In this case:

Tebako runs gem install for all .gem files in the root folder, in random order.
The entry point follows the same logic as in the Gem Packaging scenario (<memfs root>/bin/<entry point>).

No Magic, Just Standard Ruby Behavior

When asked why we do not provide an option for the user to select a packaging scenario, we explain that doing so would introduce potential errors and confusion. The contents of the root folder must always match the appropriate packaging scenario, leaving little room for flexibility.

Tebako does not introduce any magic; it simply follows well-established Ruby practices. What is uncommon is to see all packaging methods supported in a single script—this is usually unnecessary unless you require a universal packager.

Have a happy packaging!

Contact information

https://github.com/tamatebako/tebako/issues

The team is always on the watch for making things easier for Tebako users.

Press on with Tebako!