guides_packaging

---

category: "🔨 Build/Deployment" version: "v1.3.0" status: "✅" date: "22.12.2025"

🔨 ThemisDB Packaging Guide

Guide to building and distributing packages across platforms.

📋 Inhaltsverzeichnis

• 📋 Übersicht
• ✨ Features
• 🚀 Quick Start
• 📖 Linux Distributions
• 💡 Best Practices
• 🔧 Troubleshooting
• 📚 Weitere Ressourcen
• 📝 Changelog

---

📋 Übersicht

This document describes how to build and publish ThemisDB packages for various operating systems and package managers.

Stand: 22. Dezember 2025
Version: 1.3.0
Kategorie: 🔨 Build/Deployment

---

✨ Features

• 🐧 Linux Support - Debian/Ubuntu (.deb), Fedora/RHEL (.rpm), Arch Linux
• 🪟 Windows Support - Chocolatey, WinGet
• 🍎 macOS Support - Homebrew
• 📦 Multi-Package - Support for various package managers
• 🔄 Distribution Submission - Publishing to official repositories

---

🚀 Quick Start

Table of Contents

• Linux Distributions
  • Debian/Ubuntu (.deb)
  • Fedora/RHEL/CentOS (.rpm)
  • Arch Linux (PKGBUILD)
• Windows
  • Chocolatey
  • WinGet
• macOS
  • Homebrew
• Distribution Submission

---

Linux Distributions

Debian/Ubuntu (.deb)

ThemisDB provides Debian packaging files in the debian/ directory for building .deb packages compatible with Debian, Ubuntu, and derivatives.

Prerequisites

sudo apt-get install -y debhelper devscripts build-essential \
    cmake ninja-build pkg-config \
    libssl-dev librocksdb-dev libtbb-dev libarrow-dev \
    libboost-system-dev libspdlog-dev nlohmann-json3-dev \
    libcurl4-openssl-dev libyaml-cpp-dev libzstd-dev

Building the Package

# From the repository root
dpkg-buildpackage -us -uc -b

# Or using debuild
debuild -us -uc -b

The built packages will be placed in the parent directory:

• themisdb_1.0.0-1_amd64.deb - Main package
• themisdb-dev_1.0.0-1_amd64.deb - Development headers and libraries

Installing the Package

sudo dpkg -i ../themisdb_1.0.0-1_amd64.deb
sudo apt-get install -f  # Fix any dependency issues

Using the Installed Package

# Start the service
sudo systemctl start themisdb
sudo systemctl enable themisdb

# Check status
sudo systemctl status themisdb

# View logs
sudo journalctl -u themisdb -f

# Configuration file
sudo nano /etc/themisdb/config.yaml

# Data directory
ls -la /var/lib/themisdb/

Submitting to Debian/Ubuntu Repositories

1. Debian: Follow the Debian New Maintainer's Guide
2. Ubuntu PPA: Create a PPA on Launchpad

# Sign the package
debuild -S -sa

# Upload to PPA
dput ppa:your-ppa-name themisdb_1.0.0-1_source.changes

---

Fedora/RHEL/CentOS (.rpm)

ThemisDB provides an RPM spec file at themisdb.spec for building RPM packages.

Prerequisites

# Fedora/RHEL/CentOS
sudo dnf install -y rpm-build rpmdevtools
sudo dnf install -y gcc-c++ cmake ninja-build git pkg-config \
    openssl-devel rocksdb-devel tbb-devel arrow-devel \
    boost-devel spdlog-devel json-devel \
    libcurl-devel yaml-cpp-devel libzstd-devel

Setting Up Build Environment

# Create RPM build directory structure
rpmdev-setuptree

# Download source tarball
cd ~/rpmbuild/SOURCES
wget https://github.com/makr-code/ThemisDB/archive/v1.0.0.tar.gz

# Copy spec file
cp /path/to/ThemisDB/themisdb.spec ~/rpmbuild/SPECS/

Building the Package

cd ~/rpmbuild/SPECS
rpmbuild -ba themisdb.spec

Built packages are placed in:

• ~/rpmbuild/RPMS/x86_64/themisdb-1.0.0-1.x86_64.rpm - Main package
• ~/rpmbuild/RPMS/x86_64/themisdb-devel-1.0.0-1.x86_64.rpm - Development package

Installing the Package

sudo dnf install ~/rpmbuild/RPMS/x86_64/themisdb-1.0.0-1.x86_64.rpm

Using the Installed Package

# Start the service
sudo systemctl start themisdb
sudo systemctl enable themisdb

# Check status
sudo systemctl status themisdb

# Configuration file
sudo nano /etc/themisdb/config.yaml

# Data directory
ls -la /var/lib/themisdb/

Submitting to Fedora/RHEL Repositories

1. Fedora: Follow the Fedora Package Maintainer Guide
2. EPEL: Submit to EPEL for RHEL/CentOS compatibility
3. Copr: Create a repository on Copr

---

Arch Linux (PKGBUILD)

ThemisDB provides a PKGBUILD file for building Arch Linux packages.

Prerequisites

sudo pacman -S base-devel git cmake ninja
sudo pacman -S openssl rocksdb intel-tbb arrow boost spdlog \
               nlohmann-json curl yaml-cpp zstd

Building the Package

# Create a build directory
mkdir -p ~/build/themisdb
cd ~/build/themisdb

# Copy PKGBUILD and service file
cp /path/to/ThemisDB/PKGBUILD .
cp /path/to/ThemisDB/debian/themisdb.service .

# Build the package
makepkg -si

This will download the source, build ThemisDB, and install it automatically.

Manual Installation

# Build without installing
makepkg

# Install the built package
sudo pacman -U themisdb-1.0.0-1-x86_64.pkg.tar.zst

Using the Installed Package

# Start the service
sudo systemctl start themisdb
sudo systemctl enable themisdb

# Check status
sudo systemctl status themisdb

# Configuration file
sudo nano /etc/themisdb/config.yaml

Submitting to AUR

1. Create an account on AUR
2. Clone the AUR repository:

   git clone ssh://aur@aur.archlinux.org/themisdb.git
   cd themisdb

3. Add files:

   cp /path/to/PKGBUILD .
   cp /path/to/themisdb.service .
   
   # Generate .SRCINFO
   makepkg --printsrcinfo > .SRCINFO

4. Commit and push:

   git add PKGBUILD .SRCINFO themisdb.service
   git commit -m "Initial commit: themisdb 1.0.0"
   git push

---

Windows

Chocolatey

ThemisDB provides Chocolatey packaging files in packaging/chocolatey/.

Prerequisites

• Windows PowerShell or PowerShell Core
• Chocolatey installed
• Visual Studio 2019+ or Build Tools

Building the Package

1. Build ThemisDB for Windows:

   .\build.ps1 -BuildType Release

2. Create release archive:

   # Create distribution directory
   $version = "1.0.0"
   $distDir = "dist\themisdb-$version-win64"
   New-Item -ItemType Directory -Force -Path $distDir\bin
   
   # Copy binaries
   Copy-Item build-msvc\Release\themis_server.exe $distDir\bin\
   Copy-Item config\config.yaml $distDir\
   
   # Create ZIP archive
   Compress-Archive -Path $distDir\* -DestinationPath "themisdb-$version-win64.zip"

3. Calculate SHA256 checksum:

   Get-FileHash themisdb-$version-win64.zip -Algorithm SHA256

4. Update packaging/chocolatey/tools/chocolateyinstall.ps1 with the checksum

5. Build Chocolatey package:

   cd packaging\chocolatey
   choco pack

Testing the Package Locally

choco install themisdb -s . -f

Submitting to Chocolatey Community Repository

1. Create an account on Chocolatey Community
2. Get your API key from your account settings
3. Push the package:

   choco apikey --key YOUR-API-KEY --source https://push.chocolatey.org/
   choco push themisdb.1.0.0.nupkg --source https://push.chocolatey.org/

---

WinGet

ThemisDB provides WinGet manifest files in packaging/winget/manifests/.

Prerequisites

• Windows 10 1809+ or Windows 11
• WinGet installed

Testing the Manifest Locally

# Validate manifest
winget validate --manifest packaging\winget\manifests\t\ThemisDB\ThemisDB\1.0.0\

# Install from local manifest
winget install --manifest packaging\winget\manifests\t\ThemisDB\ThemisDB\1.0.0\ThemisDB.ThemisDB.yaml

Submitting to WinGet Community Repository

1. Fork microsoft/winget-pkgs
2. Create a new branch:

   git checkout -b themisdb-1.0.0

3. Copy manifest files:

   mkdir -p manifests/t/ThemisDB/ThemisDB/1.0.0
   cp packaging/winget/manifests/t/ThemisDB/ThemisDB/1.0.0/* \
      manifests/t/ThemisDB/ThemisDB/1.0.0/

4. Update the SHA256 hash in the installer manifest
5. Commit and create a pull request to the upstream repository

---

macOS

Homebrew

ThemisDB provides a Homebrew Formula at packaging/homebrew/themisdb.rb.

Prerequisites

• macOS 11+
• Homebrew installed
• Xcode Command Line Tools

Building from Formula

# Install dependencies
brew install cmake ninja pkg-config openssl@3 rocksdb tbb \
             apache-arrow boost spdlog nlohmann-json curl yaml-cpp zstd

# Build from local formula
brew install --build-from-source packaging/homebrew/themisdb.rb

Testing the Formula

# Test the formula
brew test themisdb

# Audit the formula
brew audit --strict themisdb

Using the Installed Package

# Start the service
brew services start themisdb

# Check status
brew services list | grep themisdb

# View logs
tail -f /opt/homebrew/var/log/themisdb.log

# Configuration file
nano /opt/homebrew/etc/themisdb/config.yaml

Submitting to Homebrew Core

1. Fork Homebrew/homebrew-core
2. Create a new branch:

   git checkout -b themisdb

3. Add the formula:

   cp packaging/homebrew/themisdb.rb Formula/themisdb.rb

4. Update the SHA256 hash:

   # Download source tarball
   curl -L https://github.com/makr-code/ThemisDB/archive/v1.0.0.tar.gz \
        -o themisdb-1.0.0.tar.gz
   
   # Calculate hash
   shasum -a 256 themisdb-1.0.0.tar.gz
   
   # Update in Formula/themisdb.rb

5. Test the formula:

   brew install --build-from-source Formula/themisdb.rb
   brew test themisdb
   brew audit --strict themisdb

6. Commit and create a pull request

---

Distribution Submission

Pre-Submission Checklist

Before submitting to any distribution repository:

• Verify all dependencies are correctly listed
• Test package installation on a clean system
• Test package upgrade from previous version
• Test package removal/uninstallation
• Verify systemd service (Linux) works correctly
• Check file permissions and ownership
• Ensure configuration files are marked as config files
• Test that data directories are preserved on upgrade
• Verify license information is correct
• Update changelog/release notes

Distribution-Specific Guidelines

Each distribution has specific requirements:

• Debian: Follow Debian Policy Manual
• Fedora: Follow Fedora Packaging Guidelines
• Arch: Follow Arch Packaging Standards
• Chocolatey: Follow Chocolatey Package Guidelines
• WinGet: Follow WinGet Manifest Guidelines
• Homebrew: Follow Homebrew Formula Cookbook

Community Repositories

For faster adoption, consider submitting to community-maintained repositories first:

• Ubuntu PPA: Personal Package Archive on Launchpad
• Fedora Copr: Community projects repository
• AUR: Arch User Repository
• Homebrew Tap: Custom Homebrew repository

Example of creating a Homebrew Tap:

# Create tap repository
git clone https://github.com/makr-code/homebrew-themisdb
cd homebrew-themisdb
mkdir Formula
cp ../ThemisDB/packaging/homebrew/themisdb.rb Formula/

# Users can then install with:
# brew tap makr-code/themisdb
# brew install themisdb

---

Manual Package Builds

All packages should be built manually/offline before distribution. The packaging files provided support building on the target platform or in Docker containers for reproducibility.

Building in Docker Containers

For consistent builds across environments, use Docker containers:

Debian/Ubuntu:

docker run -it --rm -v $(pwd):/build ubuntu:22.04
cd /build
apt-get update && apt-get install -y debhelper devscripts build-essential
dpkg-buildpackage -us -uc -b

Fedora/RHEL:

docker run -it --rm -v $(pwd):/build fedora:39
cd /build
dnf install -y rpm-build rpmdevtools
rpmdev-setuptree
rpmbuild -ba themisdb.spec

Arch Linux:

docker run -it --rm -v $(pwd):/build archlinux:latest
cd /build
pacman -Syu --noconfirm base-devel
makepkg

Note: Automated CI/CD builds via GitHub Actions are planned for future releases but should be implemented after initial manual testing and distribution approval.

---

Support

For packaging issues or questions:

• GitHub Issues: https://github.com/makr-code/ThemisDB/issues
• Documentation: https://makr-code.github.io/ThemisDB/
• Email: service@themisdb.org