# Installation Files Summary

This document lists all the installation and setup files created for the Archipelago project.

## Created Files

### 1. **INSTALL.sh** (Main Installation Script)
- Automated installation of all dependencies
- Installs: Homebrew, Rust, Node.js, Podman, PostgreSQL
- Installs all project dependencies
- Builds the backend
- **Run:** `./INSTALL.sh`

### 2. **verify-install.sh** (Verification Script)
- Checks if all dependencies are installed
- Validates configuration
- Provides helpful error messages
- **Run:** `./verify-install.sh`

### 3. **GETTING_STARTED.md** (Quick Start Guide)
- Step-by-step installation guide
- Multiple development modes
- Troubleshooting tips
- Success checklist

### 4. **SETUP_GUIDE.md** (Detailed Setup Documentation)
- Comprehensive installation instructions
- Manual installation steps
- Environment configuration
- Common issues and solutions
- Development workflow

### 5. **QUICK_REFERENCE.md** (Command Cheatsheet)
- All common commands
- Configuration examples
- Troubleshooting commands
- Useful aliases

### 6. **core/.env.example** (Backend Config Template)
- Example environment variables for backend
- Copy to `core/.env` to use

### 7. **neode-ui/.env.example** (Frontend Config Template)
- Example environment variables for frontend
- Copy to `neode-ui/.env` to use

### 8. **README.md** (Updated)
- Added links to new installation guides
- Updated quick start section
- Fixed paths to use current project structure

## Installation Flow

```
┌─────────────────────────┐
│   Start Installation    │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Run ./INSTALL.sh      │
│                         │
│  ├─ Install Homebrew    │
│  ├─ Install Rust        │
│  ├─ Install Node.js     │
│  ├─ Install Podman      │
│  ├─ Install PostgreSQL  │
│  ├─ Install npm deps    │
│  └─ Build backend       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Run ./verify-install.sh │
│                         │
│  Check all dependencies │
│  are properly installed │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Configure (Optional)  │
│                         │
│  cp core/.env.example   │
│     core/.env           │
│                         │
│  cp neode-ui/.env.ex... │
│     neode-ui/.env       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│  Start Development      │
│                         │
│  Terminal 1: Backend    │
│  cd core && cargo run   │
│                         │
│  Terminal 2: Frontend   │
│  cd neode-ui && npm dev │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│  Open Browser           │
│  http://localhost:8100  │
└─────────────────────────┘
```

## File Purposes

| File | Purpose | Run/Use |
|------|---------|---------|
| `INSTALL.sh` | Install all dependencies | `./INSTALL.sh` |
| `verify-install.sh` | Verify installation | `./verify-install.sh` |
| `GETTING_STARTED.md` | Quick start guide | Read first |
| `SETUP_GUIDE.md` | Detailed setup docs | Reference |
| `QUICK_REFERENCE.md` | Command cheatsheet | Reference |
| `core/.env.example` | Backend config template | Copy to `.env` |
| `neode-ui/.env.example` | Frontend config template | Copy to `.env` |

## What Each Script Does

### INSTALL.sh
```bash
✓ Checks if Homebrew is installed
✓ Installs Homebrew if needed
✓ Installs Rust via rustup
✓ Installs Node.js via Homebrew
✓ Installs Podman via Homebrew
✓ Initializes Podman machine
✓ Installs PostgreSQL via Homebrew
✓ Starts PostgreSQL service
✓ Installs frontend dependencies (neode-ui)
✓ Installs custom app dependencies
✓ Builds Rust backend
✓ Displays next steps
```

### verify-install.sh
```bash
✓ Checks Rust compiler and Cargo
✓ Checks Node.js and NPM
✓ Checks Podman installation
✓ Checks PostgreSQL installation
✓ Verifies frontend dependencies
✓ Verifies custom app dependencies
✓ Checks backend build status
✓ Checks Podman machine status
✓ Checks PostgreSQL service status
✓ Checks environment files
✓ Reports missing dependencies
✓ Provides fix suggestions
```

## Required vs Optional Dependencies

### Required (Must Install)
- ✅ **Rust** - Backend compilation
- ✅ **Node.js** - Frontend and custom apps
- ✅ **npm** - JavaScript package manager

### Recommended (For Full Features)
- ⚠️ **Podman** - Container runtime for apps
- ⚠️ **PostgreSQL** - Database for backend

### Optional (Can Install Later)
- 💡 **Homebrew** - Package manager (makes installation easier)
- 💡 **cargo-watch** - Auto-reload for backend development

## Minimum Requirements

To run the project with minimal setup:

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js (download from nodejs.org)
# Or use version manager like nvm

# Install dependencies
cd neode-ui && npm install

# Run with mock backend (no PostgreSQL needed)
npm run dev:mock
```

## Full Setup (All Features)

For full functionality including containers and database:

```bash
# Run the full installation
./INSTALL.sh

# Verify everything
./verify-install.sh

# Start development
cd core && cargo run --bin archipelago      # Terminal 1
cd neode-ui && npm run dev                   # Terminal 2
```

## Usage Examples

### First Time Setup
```bash
# Clone the repository
cd ~/Projects/archy

# Install everything
./INSTALL.sh

# Verify installation
./verify-install.sh

# Copy environment files
cp core/.env.example core/.env
cp neode-ui/.env.example neode-ui/.env

# Start development
cd core && cargo run --bin archipelago
```

### Checking What's Installed
```bash
# Run verification
./verify-install.sh

# Output will show:
# ✓ Installed and working
# ⚠ Installed but needs configuration
# ✗ Not installed
```

### Quick Frontend Development
```bash
# No backend needed
cd neode-ui
npm run dev:mock

# Open http://localhost:8100
```

## Platform Support

Currently tested on:
- ✅ **macOS** (Darwin) - Intel and Apple Silicon
- 🚧 **Linux** - Coming soon
- 🚧 **Windows** - Coming soon (WSL recommended)

## Next Steps After Installation

1. **Read** [GETTING_STARTED.md](GETTING_STARTED.md)
2. **Run** `./verify-install.sh`
3. **Configure** environment files
4. **Start** development servers
5. **Open** http://localhost:8100
6. **Build** apps in `apps/` directory
7. **Read** documentation in `docs/`

## Troubleshooting

If installation fails:

1. Check `./verify-install.sh` output
2. Read error messages carefully
3. Consult [SETUP_GUIDE.md](SETUP_GUIDE.md)
4. Check [QUICK_REFERENCE.md](QUICK_REFERENCE.md) troubleshooting section

## Resources

- [GETTING_STARTED.md](GETTING_STARTED.md) - Start here
- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Detailed guide
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Commands
- [README.md](README.md) - Project overview
- [docs/development-setup.md](docs/development-setup.md) - Development info
- [apps/QUICKSTART.md](apps/QUICKSTART.md) - Building apps