Custom Software

OpenFactory can build and install software from your own GitHub repositories as native .deb or .rpm packages. Provide a repository with standard packaging metadata, and OpenFactory handles the rest — building, publishing, and installing your software into the OS image.

How It Works

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐     ┌──────────────┐
│  GitHub Repo │ ──▶ │  Package Builder │ ──▶ │  Package Repo│ ──▶ │   OS Image   │
│  (your code) │     │  (automated)     │     │  (APT / DNF) │     │   (.iso)     │
└──────────────┘     └──────────────────┘     └──────────────┘     └──────────────┘

1. You provide a GitHub repository URL containing Debian or RPM packaging metadata
2. OpenFactory’s build service clones the repo and builds a native package (.deb or .rpm)
3. The built package is published to a package repository
4. During the OS image build, the package is installed from that repository

Preparing Your Repository

Debian Packages (APT)

Your repository must contain a debian/ directory at the root (or on the target branch) with the standard Debian packaging files.

Required files:

Optional files:

Minimal debian/control

Source: my-agent
Section: utils
Priority: optional
Maintainer: Your Name <you@example.com>
Build-Depends: debhelper-compat (= 13)

Package: my-agent
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: Custom monitoring agent
 A lightweight monitoring agent that reports system metrics.

Minimal debian/changelog

my-agent (1.0.0-1) stable; urgency=medium

  * Initial release.

 -- Your Name <you@example.com>  Mon, 07 Apr 2026 12:00:00 +0000

Minimal debian/rules

#!/usr/bin/make -f
%:
	dh $@
 
override_dh_auto_install:
	install -D -m 0755 my-agent $(CURDIR)/debian/my-agent/usr/bin/my-agent

Tip: The debian/changelog version (1.0.0-1 above) becomes the installed package version. Increment it for each release.

RPM Packages (DNF)

Your repository must contain a .spec file at the root.

Key spec file sections:

Minimal .spec file

Name:           my-agent
Version:        1.0.0
Release:        1%{?dist}
Summary:        Custom monitoring agent

License:        MIT
Source0:        %{name}-%{version}.tar.gz

%description
A lightweight monitoring agent that reports system metrics.

%prep
%autosetup

%build
make %{?_smp_mflags}

%install
install -D -m 0755 my-agent %{buildroot}%{_bindir}/my-agent

%files
%{_bindir}/my-agent

Recipe Configuration

There are three recipe fields for including custom software in your build.

custom_packages

Specify GitHub repositories to build as native packages.

{
  "custom_packages": [
    {
      "name": "my-agent",
      "git_url": "https://github.com/myorg/my-agent.git",
      "branch": "main"
    }
  ]
}

OpenFactory clones the repository, detects the packaging format (debian/ or .spec), builds the package, and installs it into the image.

extra_repos

Add existing APT or DNF repository URLs as package sources. Any packages they provide become available for installation.

{
  "extra_repos": [
    "deb http://packages.example.com/debian stable main"
  ]
}

Use this when your packages are already hosted in a repository and don’t need to be built from source.

package_overrides

Fine-grained control over the package list. Add packages not covered by features, remove unwanted packages, or replace default packages with alternatives.

{
  "package_overrides": [
    {
      "name": "my-custom-tool",
      "action": "add"
    },
    {
      "name": "nano",
      "action": "replace",
      "replacement": "neovim"
    },
    {
      "name": "telnet",
      "action": "remove"
    }
  ]
}

Natural Language Examples

You don’t need to write JSON directly. Describe what you want to OpenFactory:

Adding a Custom Package

Build a Debian server with my custom monitoring agent from
https://github.com/myorg/monitoring-agent

Adding Multiple Packages

Include these custom packages in my Ubuntu build:
- https://github.com/myorg/config-daemon (branch: release/v2)
- https://github.com/myorg/health-checker

Using a Custom Repository

Add the repository at http://packages.mycompany.com/debian stable main
and install mycompany-tools from it

Replacing a Default Package

Replace the default openssh-server with our patched version from
https://github.com/myorg/openssh-patched

Simple Package Additions

Also install: prometheus-node-exporter, collectd, grafana-agent

Package Build Lifecycle

When you include a custom_packages entry:

1. OpenFactory clones your repository from the specified URL and branch
2. The packaging format is detected automatically (debian/ directory for .deb, .spec file for .rpm)
3. The package is built using standard tooling (dpkg-buildpackage or rpmbuild) targeting the correct distribution
4. Built packages are published to a package repository
5. The repository URL is added to the build configuration as an extra_repos entry
6. During the image build, apt-get install (or dnf install) pulls the package from the repository

Build status progresses through: pending → building → succeeded (or failed).

Supported Distributions

All Debian-based distributions use the same debian/ packaging structure. Fedora uses .spec files.

Troubleshooting

Package build fails

• Verify debian/control lists all build dependencies in Build-Depends
• Check that debian/changelog has a valid version format (e.g., 1.0.0-1)
• Ensure debian/rules is executable (chmod +x debian/rules)
• For RPM builds, verify the .spec file has all required sections

Package not found during image build

• Confirm the package build succeeded before starting the image build
• Check that the package name in debian/control matches what you’re trying to install
• Verify your extra_repos URL is correct and accessible

Version conflicts

• Update debian/changelog with a version higher than any existing package
• Use package_overrides with action: "replace" to force your version over the default

Build-Depends not available

• Your package’s build dependencies must be available in the base distribution’s repositories
• If a build dependency is itself a custom package, build it first and add its repository to extra_repos