Installation‐and‐Setup

Installation and Setup

This page guides you through installing and setting up libfasttree in your Rust project. We'll cover prerequisites, adding the crate, and basic configuration. The process is straightforward, assuming you have Rust installed.

Prerequisites

Before installing libfasttree, ensure you have:

• Rust and Cargo: Version 1.60 or higher. Install from rustup.rs.
• SQLite: libfasttree uses SQLx with SQLite for its database. Ensure libsqlite3 is installed on your system:
  • Ubuntu/Debian: sudo apt install libsqlite3-dev
  • Fedora: sudo dnf install sqlite-devel
  • macOS: brew install sqlite
• Root Privileges: Some operations (e.g., mounting filesystems, changing ownership) require running as root or with sudo.
• Optional Dependencies:
  • For FS-Verity: A Linux kernel with FS-Verity support (4.19+).
  • For TPM: A system with TPM 2.0 hardware and tpm2-tools installed.
  • For Btrfs/XFS: Filesystems supporting reflinks.
• Build Tools: pkg-config and a C compiler for dependencies like nix and gpgme.

Note: libfasttree has many dependencies (e.g., tokio, sqlx, nix). Check the Cargo.toml for the full list.

Installing the Crate

libfasttree is published on crates.io. Add it to your Cargo.toml:

[dependencies]
libfasttree = "0.0.1"

Then, run cargo build to download and compile.

If you're cloning from GitHub for development:

git clone https://github.com/michal92299/libfasttree.git
cd libfasttree
cargo build

Setting Up the Environment

1. Create Directories: libfasttree uses paths like /var/lib/fasttree/objects for CAS. Create them with proper permissions:

   sudo mkdir -p /var/lib/fasttree/objects /sysroot /var/lib/extensions
   sudo chown $USER:$USER /var/lib/fasttree /sysroot /var/lib/extensions

2. Database Initialization: The library creates db.sqlite automatically, but ensure the path is writable.

3. TPM Configuration (Optional): If using TPM, configure the Tcti (e.g., Tcti::Tpmtis for software simulator or Tcti::Device for hardware).

4. Zstd Dictionaries (Optional): For compression, prepare dictionaries for common file types (e.g., ELF binaries). Add them to Config::zstd_dicts.

Basic Setup in Code

Import and initialize FastTree:

use libfasttree::{Config, DistroType, BootloaderType, FilesystemType, PartitioningType, FastTree};
use std::path::PathBuf;
use tss_esapi::tcti::Tcti;
use tokio;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = Config {
        repo_url: "http://deb.debian.org/debian".to_string(),
        distro_type: DistroType::Apt,
        cas_dir: PathBuf::from("/var/lib/fasttree/objects"),
        db_path: PathBuf::from("/var/lib/fasttree/db.sqlite"),
        deployments_dir: PathBuf::from("/sysroot"),
        current_link: PathBuf::from("/ostree/current"),
        boot_dir: PathBuf::from("/boot"),
        bootloader: BootloaderType::SystemdBoot,
        filesystem: FilesystemType::Btrfs,
        health_check_script: None,
        overlay_dirs: vec![PathBuf::from("/etc")],
        var_volume: None,
        gpg_keyring: PathBuf::from("/etc/apt/trusted.gpg"),
        use_fsverity: false,
        use_ima: false,
        partitioning: PartitioningType::Subvolumes,
        sysext_dir: PathBuf::from("/var/lib/extensions"),
        zstd_dicts: std::collections::HashMap::new(),
        tpm_tcti: Tcti::Tpmtis,
    };

    let mut ft = FastTree::new(config).await?;
    // Now use ft for operations
    Ok(())
}

Testing the Setup

Run a simple test: cargo run. If it initializes without errors, you're set. For root-required ops, use sudo cargo run.

Common Issues

• Permission Denied: Run with sudo or adjust ownership.
• Missing Dependencies: Install system packages for crates like nix (e.g., libudev-dev).
• TPM Errors: Ensure TPM is enabled in BIOS and tools are installed.

Next: Proceed to Configuration Guide for detailed config options.

Last updated: February 11, 2026