Basic‐Usage

Basic Usage: Installing and Deploying

This page introduces the core operations of libfasttree: installing packages, building trees, committing changes, and deploying them. We'll walk through examples step-by-step, assuming you've set up the library as described in the Installation and Setup and Configuration Guide pages. All examples use async Rust code with Tokio.

Overview of the Workflow

1. Resolve Dependencies: Use a solver to find required packages.
2. Download and Verify: Fetch packages and check signatures (e.g., via Sigstore).
3. Extract and Store in CAS: Extract files, compute hashes, compress/deduplicate, and store in content-addressed storage.
4. Build Tree: Assemble an immutable filesystem tree from CAS objects.
5. Commit Tree: Record the tree in the database with references.
6. Deploy: Link the tree as current, set up overlays, update bootloader.

libfasttree handles most of this automatically via high-level methods like install and deploy.

Example: Installing a Package

The install method orchestrates the full process for a package and its dependencies.

use libfasttree::{Config, FastTree /* other imports from config */};
use std::path::PathBuf;
use tss_esapi::tcti::Tcti;
use tokio;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = Config {
        // Fill in as per Configuration Guide
        repo_url: "http://deb.debian.org/debian".to_string(),
        distro_type: DistroType::Apt,
        // ... other fields ...
    };

    let mut ft = FastTree::new(config).await?;

    // Install "nginx" to the "stable" reference
    ft.install("nginx", "stable").await?;

    println!("Installation complete!");
    Ok(())
}

What Happens Under the Hood

• resolve_dependencies: Fetches metadata and solves deps using a mock libsolv.
• download_package: Downloads and verifies with Sigstore/Cosign.
• extract_to_temp: Extracts to a temp dir, collects metadata (mode, uid, etc.).
• store_in_cas: Computes hashes, chunks files for dedup, compresses with Zstd (using dictionaries if set), applies FS-Verity/IMA, stores in DB and filesystem.
• build_tree: Assembles the tree, optionally snapshots (Btrfs), signs with TPM if enabled.
• commit_tree: Saves tree hash, packages, and ref in DB.
• generate_delta: Creates bsdiff delta from previous tree (if exists).
• deploy: Calls deploy("stable") internally.

Run with sudo cargo run if root ops are needed.

Example: Deploying a Reference

If you have a committed tree (e.g., from a previous install), deploy it separately:

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = /* ... */;
    let mut ft = FastTree::new(config).await?;

    // Deploy the "stable" ref
    ft.deploy("stable").await?;

    println!("Deployment complete!");
    Ok(())
}

Deployment Steps

• Queries DB for tree hash.
• Symlinks to /ostree/current (or configured path).
• Sets up OverlayFS for writable layers (e.g., /etc ephemeral changes).
• Merges configs with 3-way merge for /etc.
• Updates bootloader (Grub or systemd-boot) with new root flags.
• Loads sysext extensions.
• Runs health check if configured.

Handling Errors and Rollbacks

If deployment fails (e.g., health check), use rollback:

ft.rollback().await?;

This switches to the previous tree hash and redeploys.

Tips for Basic Usage

• Refs: Use meaningful names like "stable", "testing" for branches.
• Testing: Start with use_fsverity: false and non-root to avoid kernel dependencies.
• Monitoring: Check DB (db.sqlite) with SQLite tools for trees/refs.
• Performance: On NVMe, async I/O shines for large installs.

For more on security during installs, see Security Features.

Next: Security Features

Last updated: February 11, 2026