Getting Started with DistroPack

Welcome to DistroPack! This guide will help you create your first Linux package and distribute it to your users. Whether you're packaging a CLI tool, a web application, or any other software, we'll walk you through the process step by step.

Quick Links

Go to Dashboard User Guide CI/CD Integration

Key Concepts

Before we start, let's understand the core concepts DistroPack uses to organize your packages:

📁 Projects

A Project is a logical grouping of related packages. For example, if you're distributing multiple versions or variants of the same software, they would belong to the same project. Projects help you organize your packages and share common settings.

📦 Packages

A Package represents a single software package you want to distribute. Each package has its own metadata (name, version, description), build targets (Debian, RPM, Arch), and files. You can have multiple packages within a project.

📄 Files

Files are the source files you upload for building packages. These could be binaries, source code, configuration files, or any other files your package needs. Files are uploaded with reference IDs (like "source-tarball" or "changelog") that you'll use when configuring builds.

🏗️ Build Targets

Build Targets define which Linux distributions and architectures you want to build for. DistroPack supports Debian (.deb), Fedora/RHEL (.rpm), and Arch Linux (.pkg.tar.zst) packages. You can enable multiple targets and architectures for each package.

🔨 Builds

A Build is the process of converting your files into distribution-specific packages. When you trigger a build, DistroPack creates packages for all enabled targets and architectures. Successful builds are automatically added to your hosted repositories.

📚 Repositories

Repositories are automatically created and maintained by DistroPack. Once a build completes, packages are added to your repository, metadata is generated, and everything is GPG-signed. Your users can install packages using standard package managers (apt, dnf, pacman).

The DistroPack Workflow

Here's the typical workflow for creating and distributing a package:

  1. Create a Project - Organize your packages
  2. Create a Package - Set up package metadata and build targets
  3. Upload Files - Add the files needed for your package
  4. Trigger a Build - Convert files into distribution packages
  5. Share the Install Link - Distribute the installation URL to your users

Step-by-Step Tutorial

Step 1

Create Your First Project

Start by creating a project to organize your packages. Projects help you group related packages together.

  1. Go to your Dashboard
  2. Click the "Create Project" button
  3. Enter a project name (e.g., "My Application")
  4. Add an optional description
  5. Click "Create"
Tip: Choose a descriptive name that represents your software or organization.
Step 2

Create a Package

Now create a package within your project. This is where you'll configure package metadata and build targets.

  1. From your project page, click "Create Package"
  2. Enter a package name (e.g., "myapp")
  3. Set the package version (e.g., "1.0.0")
  4. Add a description of your package
  5. Choose which distributions to build for (Debian, RPM, Arch)
  6. Select target architectures (x86, x64, ARM, ARM64)
  7. Click "Create"
Note: Package names should follow Linux package naming conventions (lowercase, no spaces, alphanumeric characters and hyphens only).
Step 3

Upload Files

Upload the files needed for your package. These could be binaries, source code, or configuration files.

  1. From your package page, go to the "Files" section
  2. Click "Upload File"
  3. Enter a reference ID (e.g., "source-tarball", "binary", "changelog")
  4. Select the file to upload
  5. Click "Upload"
Tip: Use descriptive reference IDs that make it clear what each file is for. Common examples: "source-tarball", "binary-x64", "changelog", "readme".
Step 4

Configure Package Metadata

Set up package metadata like maintainer information, dependencies, and custom scripts.

  1. Go to your package's settings page
  2. Add package dependencies (if any)
  3. Optionally add pre/post-install scripts
  4. Save your changes
Note: Dependencies should be specified using distribution-specific package names (e.g., "libssl-dev" for Debian, "openssl-devel" for RPM).
Step 5

Trigger Your First Build

Once your files are uploaded and metadata is configured, trigger a build to create packages.

  1. Go to your package's build page
  2. Verify that all required files are uploaded
  3. Enter a version number
  4. Click "Build Package"
  5. Monitor the build status
Success! Once the build completes, your packages will be automatically added to your repository and ready for distribution.
Step 6

Share Your Package

Distribute your package to users by sharing the installation link.

  1. After a successful build, go to your package page
  2. Click "Share Package" or find the install link
  3. Copy the installation URL
  4. Share it with your users or add it to your documentation
Tip: The installation page includes distribution-specific instructions (apt, dnf, pacman) and GPG key setup, so your users can install with standard package managers.

Common Use Cases

Packaging a CLI Tool

If you're packaging a command-line tool, you'll typically upload a single binary file. Set the binary path in your package configuration, and DistroPack will place it in the correct location (usually /usr/bin or /usr/local/bin).

Packaging a Web Application

For web applications, you might upload multiple files: a tarball with your application files, a systemd service file, and configuration templates. Use pre-install scripts to set up directories and post-install scripts to enable services.

Multi-Architecture Builds

DistroPack makes it easy to build for multiple architectures. Simply enable the architectures you need (x86, x64, ARM, ARM64) and upload architecture-specific binaries. The build system will create separate packages for each architecture automatically.

Next Steps

Now that you've created your first package, here are some things to explore:

  • Read the User Guide for detailed information about all features
  • Set up CI/CD integration to automate your builds
  • Learn about API tokens for programmatic access
  • Explore advanced features like custom scripts and dependencies

Need Help?

If you run into issues, here are some common solutions:

  • Build failures: Check that all required files are uploaded and file paths are correct
  • Upload errors: Verify file sizes are within your tier limits
  • Version errors: Ensure the version number is newer than previous builds
  • Repository access: Make sure your subscription is active

For more help, check out the User Guide or contact support.