Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deuxfleurs-org/garage/llms.txt

Use this file to discover all available pages before exploring further.

Garage is a standard Rust project that can be compiled from source. Building from source allows you to customize the build with specific feature flags and ensures you have the latest version.

​
Prerequisites

​
Rust Toolchain

You need Rust and Cargo installed on your system. 
sudo apt-get update
sudo apt-get install -y rustc cargo
Rustup is the recommended way to install Rust as it allows easy version management and always provides the latest stable toolchain.

​
C Toolchain

A full C toolchain is required for building Garage’s dependencies. 
sudo apt-get update
sudo apt-get install build-essential

​
Building from Source

1

Clone the repository

The primary location for Garage’s source code is the Forgejo repository.
git clone https://git.deuxfleurs.fr/Deuxfleurs/garage.git
cd garage
2

Checkout a specific version (optional)

To build a specific version of Garage, check out the corresponding tag:
# List available tags
git tag

# Checkout a specific version
git checkout v0.8.0
If you skip this step, you’ll be building from the main branch, which contains development code for the next version. Development builds may be unstable, contain bugs, or be incompatible with stable versions.
3

Build Garage

Build a release version of Garage:
cargo build --release
The compilation process may take several minutes depending on your hardware.
4

Install the binary

The compiled binary is located at target/release/garage. Copy it to a location in your $PATH:
sudo cp target/release/garage /usr/local/bin/garage
Verify the installation:
garage --version

​
Development Builds

If you’re developing Garage, you can create debug builds that compile faster but run slower: 
cargo build
The debug binary will be located at target/debug/garage.

​
Cargo Feature Flags

Garage supports several compilation options through Cargo feature flags. These allow you to customize the build for your specific use case.

​
Building with Custom Features

# Build with default features plus additional ones
cargo build --release --features consul-discovery,kubernetes-discovery,k2v

​
Available Feature Flags

Feature FlagDefaultDescription
bundled-libs✅Use bundled versions of sqlite3, zstd, lmdb, and libsodium
lmdb✅Enable using LMDB to store Garage’s metadata
sqlite✅Enable using SQLite3 to store Garage’s metadata
metrics✅Enable Prometheus metrics collection on the admin API
consul-discovery❌Enable automatic node discovery through Consul API
kubernetes-discovery❌Enable automatic node discovery through Kubernetes API
k2v❌Enable the experimental K2V API
fjall❌Enable using Fjall to store Garage’s metadata (experimental)
journald❌Enable logging to systemd-journald
syslog❌Enable logging to Syslog
telemetry-otlp❌Enable OpenTelemetry execution traces
system-libs❌Use system versions of libraries (exclusive with bundled-libs)
If you enable the k2v feature, all nodes in your Garage cluster must have it enabled for compatibility.

​
Build Configuration

Garage uses the following release profile settings (defined in Cargo.toml): 
[profile.release]
lto = "thin"              # Thin link-time optimization
codegen-units = 16        # Parallel code generation
opt-level = 3             # Maximum optimization
strip = "debuginfo"       # Remove debug symbols
These settings balance compilation time with runtime performance and binary size.

​
Troubleshooting

​
Compilation Errors

If you encounter compilation errors:
  1. Update Rust: Ensure you have the latest stable Rust toolchain 
    rustup update stable
  2. Clean build artifacts: Remove old build artifacts and try again 
    cargo clean
cargo build --release
  3. Check dependencies: Ensure all system dependencies are installed

​
Out of Memory

If compilation fails due to memory constraints, reduce parallel compilation: 
cargo build --release -j 2

​
Next Steps

After building Garage:
  1. Create a configuration file
  2. Follow the Quick Start guide to set up your cluster
  3. Learn about cluster operations

​
Alternative Installation Methods

If building from source isn’t suitable for your needs:

Build docs developers (and LLMs) love

Get started for freeTalk to us