Skip to content

Commit e2f0bc5

Browse files
rhatdanrhatdan
committed
Add self-contained macOS installer package
Fixes #812 This commit adds a mechanism to create self-contained macOS installer packages (.pkg) that bundle Python and all dependencies, eliminating the need for users to install Python separately. **New Features:** 1. **PyInstaller Spec File** (ramalama.spec) - Configures PyInstaller to create standalone executable - Bundles all ramalama modules and dependencies - Includes configuration files, man pages, and shell completions - Creates macOS app bundle structure 2. **Build Script** (scripts/build_macos_pkg.sh) - Automated build process for macOS .pkg installer - Uses PyInstaller to create standalone binary - Packages everything into macOS installer format - Includes post-install script for PATH configuration - Generates installer with welcome/readme/conclusion screens 3. **GitHub Actions Workflow** (.github/workflows/build-macos-installer.yml) - Automatically builds macOS installer on release - Runs on macOS runners with proper dependencies - Uploads installer as release asset - Generates SHA256 checksums for verification - Can be triggered manually for testing 4. **Documentation** (docs/MACOS_INSTALL.md) - Comprehensive installation guide for macOS users - Multiple installation methods documented - Troubleshooting section - Prerequisites and system requirements - Uninstallation instructions 5. **README Update** - Added macOS installer as primary installation method - Links to detailed installation guide **Benefits:** - No Python installation required for end users - Single-click installation experience - Includes all dependencies in one package - Follows macOS packaging best practices - Automatic PATH configuration - Professional installer UI with instructions **Installation:** Users can now download RamaLama-VERSION-macOS-Installer.pkg from GitHub Releases and install with a simple double-click or: sudo installer -pkg RamaLama-*-macOS-Installer.pkg -target / The installer places files in /usr/local/ following macOS conventions. Signed-off-by: Daniel J Walsh <[email protected]>
1 parent 7cb202c commit e2f0bc5

File tree

5 files changed

+690
-0
lines changed

5 files changed

+690
-0
lines changed

‎.github/workflows/build-macos-installer.yml‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
name: Build macOS Installer
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
ref:
9+
description: 'Git ref to checkout (branch, tag, or commit SHA)'
10+
required: false
11+
type: string
12+
default: 'main'
13+
tag_name:
14+
description: 'Tag name for release upload (e.g., v0.1.0)'
15+
required: false
16+
type: string
17+
default: ''
18+
upload_to_release:
19+
description: 'Upload to specified release tag'
20+
required: false
21+
type: boolean
22+
default: false
23+
24+
jobs:
25+
build-macos-pkg:
26+
runs-on: macos-latest
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
with:
31+
ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.ref || '' }}
32+
33+
- name: Set up Python
34+
uses: actions/setup-python@v5
35+
with:
36+
python-version: '3.11'
37+
38+
- name: Install dependencies
39+
run: |
40+
python3 -m pip install --upgrade pip
41+
pip3 install pyinstaller
42+
pip3 install -e .
43+
44+
- name: Get version
45+
id: get_version
46+
run: |
47+
VERSION=$(cd ramalama && python3 -c "import version; print(version.version())")
48+
echo "version=$VERSION" >> $GITHUB_OUTPUT
49+
echo "RamaLama version: $VERSION"
50+
51+
- name: Build macOS package
52+
run: |
53+
./scripts/build_macos_pkg.sh
54+
55+
- name: Find built package
56+
id: find_pkg
57+
run: |
58+
PKG_FILE=$(find build/macos-pkg -name "RamaLama-*-macOS-Installer.pkg" | head -n 1)
59+
echo "pkg_file=$PKG_FILE" >> $GITHUB_OUTPUT
60+
echo "pkg_name=$(basename $PKG_FILE)" >> $GITHUB_OUTPUT
61+
echo "Found package: $PKG_FILE"
62+
63+
- name: Upload artifact
64+
uses: actions/upload-artifact@v4
65+
with:
66+
name: macos-installer
67+
path: ${{ steps.find_pkg.outputs.pkg_file }}
68+
retention-days: 30
69+
70+
- name: Calculate SHA256
71+
id: sha256
72+
run: |
73+
SHA256=$(shasum -a 256 "${{ steps.find_pkg.outputs.pkg_file }}" | cut -d' ' -f1)
74+
echo "sha256=$SHA256" >> $GITHUB_OUTPUT
75+
echo "SHA256: $SHA256"
76+
echo "$SHA256 ${{ steps.find_pkg.outputs.pkg_name }}" > "${{ steps.find_pkg.outputs.pkg_file }}.sha256"
77+
78+
- name: Upload SHA256 artifact
79+
uses: actions/upload-artifact@v4
80+
with:
81+
name: macos-installer-sha256
82+
path: ${{ steps.find_pkg.outputs.pkg_file }}.sha256
83+
retention-days: 30
84+
85+
- name: Upload to release
86+
if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.upload_to_release == 'true')
87+
uses: softprops/action-gh-release@v1
88+
with:
89+
files: |
90+
${{ steps.find_pkg.outputs.pkg_file }}
91+
${{ steps.find_pkg.outputs.pkg_file }}.sha256
92+
tag_name: ${{ github.event_name == 'release' && github.event.release.tag_name || github.event.inputs.tag_name }}
93+
env:
94+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
95+
96+
- name: Summary
97+
run: |
98+
echo "## macOS Installer Build Complete! 🎉" >> $GITHUB_STEP_SUMMARY
99+
echo "" >> $GITHUB_STEP_SUMMARY
100+
echo "- **Version**: ${{ steps.get_version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
101+
echo "- **Package**: ${{ steps.find_pkg.outputs.pkg_name }}" >> $GITHUB_STEP_SUMMARY
102+
echo "- **SHA256**: ${{ steps.sha256.outputs.sha256 }}" >> $GITHUB_STEP_SUMMARY
103+
echo "" >> $GITHUB_STEP_SUMMARY
104+
echo "### Installation" >> $GITHUB_STEP_SUMMARY
105+
echo '```bash' >> $GITHUB_STEP_SUMMARY
106+
echo "# Download and install" >> $GITHUB_STEP_SUMMARY
107+
echo "curl -LO https://github.com/${{ github.repository }}/releases/download/v${{ steps.get_version.outputs.version }}/${{ steps.find_pkg.outputs.pkg_name }}" >> $GITHUB_STEP_SUMMARY
108+
echo "sudo installer -pkg ${{ steps.find_pkg.outputs.pkg_name }} -target /" >> $GITHUB_STEP_SUMMARY
109+
echo '```' >> $GITHUB_STEP_SUMMARY
110+

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,14 @@ RamaLama eliminates the need to configure the host system by instead pulling a c
5454
<br>
5555

5656
## Install
57+
### Install on macOS (Self-Contained Installer)
58+
Download the self-contained macOS installer that includes Python and all dependencies:
59+
60+
1. Download the latest `.pkg` installer from [Releases](https://github.com/containers/ramalama/releases)
61+
2. Double-click to install, or run: `sudo installer -pkg RamaLama-*-macOS-Installer.pkg -target /`
62+
63+
See [macOS Installation Guide](docs/MACOS_INSTALL.md) for detailed instructions.
64+
5765
### Install on Fedora
5866
RamaLama is available in [Fedora](https://fedoraproject.org/) and later. To install it, run:
5967
```

‎docs/MACOS_INSTALL.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# macOS Installation Guide for RamaLama
2+
3+
This guide covers the different ways to install RamaLama on macOS.
4+
5+
## Method 1: Self-Contained Installer Package (Recommended)
6+
7+
The easiest way to install RamaLama on macOS is using our self-contained `.pkg` installer. This method includes Python and all dependencies, so you don't need to install anything else.
8+
9+
### Download and Install
10+
11+
1. Download the latest installer from the [Releases page](https://github.com/containers/ramalama/releases)
12+
2. Double-click the downloaded `.pkg` file
13+
3. Follow the installation wizard
14+
15+
Or via command line:
16+
17+
```bash
18+
# Download the installer (replace VERSION with the actual version)
19+
curl -LO https://github.com/containers/ramalama/releases/download/vVERSION/RamaLama-VERSION-macOS-Installer.pkg
20+
21+
# Verify the SHA256 checksum (optional but recommended)
22+
curl -LO https://github.com/containers/ramalama/releases/download/vVERSION/RamaLama-VERSION-macOS-Installer.pkg.sha256
23+
shasum -a 256 -c RamaLama-VERSION-macOS-Installer.pkg.sha256
24+
25+
# Install
26+
sudo installer -pkg RamaLama-VERSION-macOS-Installer.pkg -target /
27+
```
28+
29+
### What Gets Installed
30+
31+
The installer places files in:
32+
- `/usr/local/bin/ramalama` - Main executable
33+
- `/usr/local/share/ramalama/` - Configuration files
34+
- `/usr/local/share/man/` - Man pages
35+
- `/usr/local/share/bash-completion/` - Bash completions
36+
- `/usr/local/share/fish/` - Fish completions
37+
- `/usr/local/share/zsh/` - Zsh completions
38+
39+
### Verify Installation
40+
41+
```bash
42+
# Check version
43+
ramalama --version
44+
45+
# Get help
46+
ramalama --help
47+
```
48+
49+
## Method 2: Python Package (pip)
50+
51+
If you prefer to use Python package management:
52+
53+
```bash
54+
# Install Python 3.10 or later (if not already installed)
55+
brew install [email protected]
56+
57+
# Install ramalama
58+
pip3 install ramalama
59+
60+
# Or install from source
61+
git clone https://github.com/containers/ramalama.git
62+
cd ramalama
63+
pip3 install .
64+
```
65+
66+
## Method 3: Build from Source
67+
68+
For developers or if you want the latest code:
69+
70+
```bash
71+
# Clone the repository
72+
git clone https://github.com/containers/ramalama.git
73+
cd ramalama
74+
75+
# Install build dependencies
76+
pip3 install build
77+
78+
# Build and install
79+
make install
80+
```
81+
82+
## Prerequisites
83+
84+
Before using RamaLama, you'll need a container engine:
85+
86+
### Option A: Podman (Recommended)
87+
88+
```bash
89+
brew install podman
90+
91+
# Initialize Podman machine with libkrun for GPU access
92+
podman machine init --provider libkrun
93+
podman machine start
94+
```
95+
96+
For more details, see [ramalama-macos(7)](ramalama-macos.7.md).
97+
98+
### Option B: Docker
99+
100+
```bash
101+
brew install docker
102+
```
103+
104+
## Building the Installer Package (For Maintainers)
105+
106+
If you want to build the installer package yourself:
107+
108+
```bash
109+
# Install PyInstaller
110+
pip3 install pyinstaller
111+
112+
# Build the package
113+
./scripts/build_macos_pkg.sh
114+
115+
# The built package will be in:
116+
# build/macos-pkg/RamaLama-VERSION-macOS-Installer.pkg
117+
```
118+
119+
## Uninstallation
120+
121+
To remove RamaLama:
122+
123+
```bash
124+
# Remove the executable
125+
sudo rm /usr/local/bin/ramalama
126+
127+
# Remove configuration and data files (optional)
128+
sudo rm -rf /usr/local/share/ramalama
129+
rm -rf ~/.local/share/ramalama
130+
rm -rf ~/.config/ramalama
131+
132+
# Remove man pages (optional)
133+
sudo rm /usr/local/share/man/man1/ramalama*.1
134+
sudo rm /usr/local/share/man/man5/ramalama*.5
135+
sudo rm /usr/local/share/man/man7/ramalama*.7
136+
137+
# Remove shell completions (optional)
138+
sudo rm /usr/local/share/bash-completion/completions/ramalama
139+
sudo rm /usr/local/share/fish/vendor_completions.d/ramalama.fish
140+
sudo rm /usr/local/share/zsh/site-functions/_ramalama
141+
```
142+
143+
## Troubleshooting
144+
145+
### "ramalama: command not found"
146+
147+
Make sure `/usr/local/bin` is in your PATH:
148+
149+
```bash
150+
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
151+
source ~/.zshrc
152+
```
153+
154+
### "Cannot verify developer" warning
155+
156+
macOS may show a security warning for unsigned packages. To bypass:
157+
158+
1. Right-click the `.pkg` file
159+
2. Select "Open"
160+
3. Click "Open" in the dialog
161+
162+
Or disable Gatekeeper temporarily:
163+
164+
```bash
165+
sudo spctl --master-disable
166+
# Install the package
167+
sudo spctl --master-enable
168+
```
169+
170+
### Podman machine issues
171+
172+
If Podman isn't working:
173+
174+
```bash
175+
# Reset Podman machine
176+
podman machine stop
177+
podman machine rm
178+
podman machine init --provider libkrun
179+
podman machine start
180+
```
181+
182+
## Getting Started
183+
184+
Once installed, try these commands:
185+
186+
```bash
187+
# Check version
188+
ramalama --version
189+
190+
# Pull a model
191+
ramalama pull tinyllama
192+
193+
# Run a chatbot
194+
ramalama run tinyllama
195+
196+
# Get help
197+
ramalama --help
198+
```
199+
200+
## Additional Resources
201+
202+
- [RamaLama Documentation](https://ramalama.ai)
203+
- [GitHub Repository](https://github.com/containers/ramalama)
204+
- [macOS-specific Documentation](ramalama-macos.7.md)
205+
- [Report Issues](https://github.com/containers/ramalama/issues)
206+
207+
## System Requirements
208+
209+
- macOS 10.15 (Catalina) or later
210+
- Intel or Apple Silicon (M1/M2/M3) processor
211+
- 4GB RAM minimum (8GB+ recommended for running models)
212+
- 10GB free disk space
213+
- Podman or Docker
214+

0 commit comments

Comments
 (0)