# Installation Methods

**Status**: ✅ Complete

**Phase**: Phase 7 - Integration Features

**Last Updated**: December 9, 2025

---

## Overview

RiceCoder provides multiple installation methods to suit different preferences and environments. Choose from curl script, package managers, Docker, or binary releases. All methods are supported on Windows, macOS, and Linux.

## Quick Install

### Curl Script (Recommended)

Build and install RiceCoder with a single command:

```bash
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash
```

This script:
- Detects your OS and architecture
- Checks prerequisites (Rust, Cargo, Git)
- Updates Rust toolchain
- Builds from source
- Installs to `/usr/local/bin` or custom prefix
- Adds to PATH automatically
- Verifies installation

### Homebrew (macOS/Linux)

Install via Homebrew:

```bash
brew install ricecoder
```

Update to latest version:

```bash
brew upgrade ricecoder
```

Uninstall:

```bash
brew uninstall ricecoder
```

### Cargo (Rust)

Install via Cargo:

```bash
cargo install ricecoder
```

Install specific version:

```bash
cargo install ricecoder@0.1.7
```

Update to latest:

```bash
cargo install --upgrade ricecoder
```

Uninstall:

```bash
cargo uninstall ricecoder
```

### NPM (Node.js)

Install via NPM:

```bash
npm install -g ricecoder
```

Install specific version:

```bash
npm install -g ricecoder@0.1.7
```

Update to latest:

```bash
npm update -g ricecoder
```

Uninstall:

```bash
npm uninstall -g ricecoder
```

## Platform-Specific Installation

### Windows

#### Chocolatey

Install via Chocolatey:

```powershell
choco install ricecoder
```

Update:

```powershell
choco upgrade ricecoder
```

#### Scoop

Install via Scoop:

```powershell
scoop install ricecoder
```

Update:

```powershell
scoop update ricecoder
```

#### Windows Package Manager

Install via Windows Package Manager:

```powershell
winget install ricecoder
```

Update:

```powershell
winget upgrade ricecoder
```

#### Manual Installation

Download and install manually:

1. Download latest release from [GitHub Releases](https://github.com/moabualruz/ricecoder/releases)
2. Extract to desired location
3. Add to PATH:
   - Right-click "This PC" → Properties
   - Advanced system settings → Environment Variables
   - Add installation directory to PATH
4. Verify installation: `rice --version`

### macOS

#### Homebrew (Recommended)

```bash
brew install ricecoder
```

#### MacPorts

```bash
sudo port install ricecoder
```

#### Manual Installation

1. Download latest release for macOS
2. Extract: `tar -xzf ricecoder-*.tar.gz`
3. Move to PATH: `sudo mv ricecoder /usr/local/bin/`
4. Verify: `rice --version`

### Linux

#### APT (Debian/Ubuntu)

Add repository (via GitHub raw content):

```bash
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install-apt-key.sh | sudo bash
echo "deb [signed-by=/usr/share/keyrings/ricecoder-archive-keyring.gpg] https://github.com/moabualruz/ricecoder/releases/download/latest stable main" | sudo tee /etc/apt/sources.list.d/ricecoder.list
```

Install:

```bash
sudo apt update
sudo apt install ricecoder
```

Update:

```bash
sudo apt upgrade ricecoder
```

#### YUM (RHEL/CentOS/Fedora)

Add repository (via GitHub raw content):

```bash
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install-yum-repo.sh | sudo bash
```

Install:

```bash
sudo yum install ricecoder
```

Update:

```bash
sudo yum upgrade ricecoder
```

#### Pacman (Arch Linux)

Install from AUR:

```bash
yay -S ricecoder
```

Or manually:

```bash
git clone https://aur.archlinux.org/ricecoder.git
cd ricecoder
makepkg -si
```

#### Manual Installation

1. Download latest release for Linux
2. Extract: `tar -xzf ricecoder-*.tar.gz`
3. Move to PATH: `sudo mv ricecoder /usr/local/bin/`
4. Verify: `rice --version`

## Docker Installation

### Docker Image

Pull and run Docker image:

```bash
docker pull ricecoder/ricecoder:latest
docker run -it ricecoder/ricecoder:latest rice --version
```

Run with volume mount:

```bash
docker run -it -v ~/.ricecoder:/root/.ricecoder ricecoder/ricecoder:latest rice chat
```

### Docker Compose

Create `docker-compose.yml`:

```yaml
version: '3.8'

services:
  ricecoder:
    image: ricecoder/ricecoder:latest
    container_name: ricecoder
    volumes:
      - ~/.ricecoder:/root/.ricecoder
      - ./projects:/workspace
    environment:
      - RICECODER_HOME=/root/.ricecoder
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    stdin_open: true
    tty: true
    command: rice chat
```

Run with Docker Compose:

```bash
docker-compose up -d
docker-compose exec ricecoder rice chat
```

### Dockerfile

Create custom Dockerfile:

```dockerfile
FROM ricecoder/ricecoder:latest

# Install additional tools
RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /workspace

# Set environment variables
ENV RICECODER_HOME=/root/.ricecoder

# Default command
CMD ["rice", "chat"]
```

Build and run:

```bash
docker build -t my-ricecoder .
docker run -it -v ~/.ricecoder:/root/.ricecoder my-ricecoder
```

## Binary Releases

### Download Binaries

Download pre-compiled binaries from [GitHub Releases](https://github.com/moabualruz/ricecoder/releases):

- `ricecoder-x86_64-unknown-linux-gnu` - Linux x86_64
- `ricecoder-x86_64-apple-darwin` - macOS Intel
- `ricecoder-aarch64-apple-darwin` - macOS ARM64
- `ricecoder-x86_64-pc-windows-msvc` - Windows x86_64
- `ricecoder-aarch64-unknown-linux-gnu` - Linux ARM64

### Install Binary

Extract and install:

```bash
# Linux/macOS
tar -xzf ricecoder-*.tar.gz
sudo mv ricecoder /usr/local/bin/

# Windows (PowerShell)
Expand-Archive ricecoder-*.zip
Move-Item ricecoder.exe "C:\Program Files\ricecoder\"
```

Verify installation:

```bash
rice --version
```

## Build from Source

### Using Installation Scripts (Recommended)

Automated build and installation with prerequisite checking:

**Linux/macOS**:

```bash
# Clone repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Make script executable
chmod +x scripts/install.sh

# Run installation script
./scripts/install.sh

# Verify installation
rice --version
```

**Installation Script Options**:

```bash
# Install to custom prefix
./scripts/install.sh --prefix /usr/local

# Debug build
./scripts/install.sh --debug

# Verbose output
./scripts/install.sh --verbose
```

**Windows (PowerShell)**:

```powershell
# Clone repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Run installation script
.\scripts\install.ps1

# Verify installation
rice --version
```

**Installation Script Options**:

```powershell
# Install to custom prefix
.\scripts\install.ps1 -Prefix "C:\Program Files\ricecoder"

# Debug build
.\scripts\install.ps1 -Debug

# Verbose output
.\scripts\install.ps1 -Verbose
```

**Windows (CMD)**:

```cmd
# Clone repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Run installation script
scripts\install.bat

# Verify installation
rice --version
```

**Installation Script Features**:

- ✅ Automatic OS and architecture detection
- ✅ Prerequisite verification (Rust, Cargo, Git)
- ✅ Automatic Rust toolchain update
- ✅ Configurable build mode (release/debug)
- ✅ Automatic binary installation
- ✅ Configuration file installation
- ✅ Documentation installation
- ✅ Installation verification
- ✅ PATH configuration guidance

### Manual Build and Install

For advanced users or custom builds:

**Prerequisites**:

- Rust 1.70+ ([Install Rust](https://rustup.rs/))
- Git
- C compiler (gcc/clang)

**Clone and Build**:

Clone repository:

```bash
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder
```

Build release binary:

```bash
cargo build --release
```

Binary location: `target/release/ricecoder`

Install to PATH:

```bash
# Linux/macOS
sudo cp target/release/ricecoder /usr/local/bin/

# Windows (PowerShell)
Copy-Item target/release/ricecoder.exe "C:\Program Files\ricecoder\"
```

Verify installation:

```bash
rice --version
```

## Verification

### Verify Installation

Check installation:

```bash
rice --version
# Output: ricecoder 0.1.7

rice --help
# Output: RiceCoder - Terminal-first coding assistant
```

### Verify Functionality

Test basic functionality:

```bash
# Initialize a project
rice init

# Start interactive chat
rice chat

# Generate code
rice gen --help
```

## Uninstallation

### Homebrew

```bash
brew uninstall ricecoder
```

### Cargo

```bash
cargo uninstall ricecoder
```

### NPM

```bash
npm uninstall -g ricecoder
```

### Chocolatey

```powershell
choco uninstall ricecoder
```

### Scoop

```powershell
scoop uninstall ricecoder
```

### Manual Removal

Remove binary:

```bash
# Linux/macOS
sudo rm /usr/local/bin/ricecoder

# Windows
Remove-Item "C:\Program Files\ricecoder\ricecoder.exe"
```

Remove configuration:

```bash
# Remove all RiceCoder data
rm -rf ~/.ricecoder

# Windows
Remove-Item -Recurse -Force $env:APPDATA\.ricecoder
```

## Troubleshooting

### Issue: Command not found

**Solution**: Ensure RiceCoder is in PATH:

```bash
# Check if rice is in PATH
which rice

# If not found, add to PATH manually
export PATH="/usr/local/bin:$PATH"

# Or reinstall with correct location
```

### Issue: Permission denied

**Solution**: Fix file permissions:

```bash
# Make binary executable
chmod +x /usr/local/bin/ricecoder

# Or reinstall with sudo
sudo cargo install ricecoder
```

### Issue: Version mismatch

**Solution**: Update to latest version:

```bash
# Using Homebrew
brew upgrade ricecoder

# Using Cargo
cargo install --upgrade ricecoder

# Using NPM
npm update -g ricecoder

# Using curl script (from GitHub)
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash
```

### Issue: Docker image not found

**Solution**: Pull latest image:

```bash
docker pull ricecoder/ricecoder:latest
docker run -it ricecoder/ricecoder:latest rice --version
```

## Platform Support

| Platform | Status | Installation Methods |
|----------|--------|----------------------|
| Linux x86_64 | ✅ | Curl, APT, YUM, Pacman, Cargo, NPM, Docker, Binary |
| Linux ARM64 | ✅ | Curl, Cargo, NPM, Docker, Binary |
| macOS Intel | ✅ | Curl, Homebrew, MacPorts, Cargo, NPM, Docker, Binary |
| macOS ARM64 | ✅ | Curl, Homebrew, MacPorts, Cargo, NPM, Docker, Binary |
| Windows x86_64 | ✅ | Curl, Chocolatey, Scoop, WinGet, Cargo, NPM, Docker, Binary |
| Windows ARM64 | ✅ | Cargo, NPM, Docker, Binary |

## Performance

- **Curl Installation**: < 30 seconds
- **Homebrew Installation**: < 1 minute
- **Cargo Installation**: 2-5 minutes (first time)
- **Docker Pull**: < 1 minute
- **Binary Extraction**: < 5 seconds

## See Also

- [Quick Start Guide](./Quick-Start.md) - Get started after installation
- [Configuration Guide](./Configuration.md) - Configure RiceCoder
- [Troubleshooting Guide](./Troubleshooting.md) - Solve common issues
- [Architecture Overview](./Architecture-Overview.md) - System architecture

---

*Last updated: December 9, 2025*