archy/INSTALLATION_SUMMARY.md

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

✓ 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

✓ 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:

# 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:

# 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

# 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

# Run verification
./verify-install.sh

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

Quick Frontend Development

# 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
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
4. Check QUICK_REFERENCE.md troubleshooting section

Resources

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