Installing Homebrew Packages on Upsun

While Upsun provides a wide range of native runtimes, you may occasionally need a specific tool or CLI utility available via Homebrew (Linuxbrew). Because Upsun containers use a read-only file system at runtime and do not provide sudo access, Homebrew must be installed into the /app directory during the build phase.

Overview

To keep deployments fast, we use the PLATFORM_CACHE_DIR to store the Homebrew installation. This ensures that Homebrew and your installed packages persist across builds rather than being re-downloaded every time you deploy.

Implementation Steps

1. Create the Installation Script

Create a file named install_brew.sh in your project root. This script manages the "bootstrapping" of Homebrew into the persistent cache.

#!/usr/bin/env bash
set -e

# Define paths: Store brew in the persistent cache to survive deployments
BREW_CACHE="$PLATFORM_CACHE_DIR/.linuxbrew"
BREW_PATH="/app/.linuxbrew"

# 1. Initialize Homebrew if not already in cache
if [ ! -d "$BREW_CACHE" ]; then
    echo "First-time Homebrew setup..."
    mkdir -p "$BREW_CACHE"
    curl -SsL https://github.com/Homebrew/brew/tarball/master | tar xzf - --strip-components=1 -C "$BREW_CACHE"
fi

# 2. Symlink from cache to the application directory
ln -sfn "$BREW_CACHE" "$BREW_PATH"

# 3. Configure environment for the build session
export PATH="$BREW_PATH/bin:$BREW_PATH/sbin:$PATH"
export HOMEBREW_CACHE="$PLATFORM_CACHE_DIR/homebrew_downloads"

# 4. Install requested packages (passed as arguments)
if [ $# -gt 0 ]; then
    echo "Installing Homebrew packages: $*"
    brew install "$@"
    brew cleanup
fi

2. Update your .upsun/config.yaml

In Upsun, you trigger the installation within the build hook of your application. Replace package1 and package2 with the tools you need (e.g., duf, lnav, jq).

applications:
    myapp:
        # ... other config ...
        hooks:
            build: |
                set -e
                bash install_brew.sh package1 package2

3. Set Runtime Environment Variables

To ensure the brew command and your new tools are available during SSH sessions and to your application, add these variables to your .environment file:

# Add Homebrew to the PATH
export PATH="/app/.linuxbrew/bin:/app/.linuxbrew/sbin:$PATH"

# Set Homebrew specific paths
export HOMEBREW_CELLAR="/app/.linuxbrew/Cellar"
export HOMEBREW_REPOSITORY="/app/.linuxbrew/Homebrew"

Best Practices for Upsun

[!IMPORTANT]

Always check if a tool is available via your language's package manager (like composer, npm, or pip) first. These are natively supported by Upsun and are generally more efficient than Homebrew in a containerized environment.