Skip to content

Commit 2f99cc6

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 bb81e2b commit 2f99cc6

File tree

5 files changed

+678
-0
lines changed

5 files changed

+678
-0
lines changed

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

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

‎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)