# Archipelago Installation Checklist

Use this checklist to track your installation progress.

## Pre-Installation

- [ ] macOS system (Darwin)
- [ ] Terminal access
- [ ] Internet connection
- [ ] Administrator privileges

## Installation Steps

### Step 1: Run Installation Script

```bash
./INSTALL.sh
```

**Progress:**
- [ ] Homebrew installed
- [ ] Rust installed
- [ ] Node.js installed
- [ ] Podman installed
- [ ] PostgreSQL installed
- [ ] Frontend dependencies installed
- [ ] Custom app dependencies installed
- [ ] Backend compiled

### Step 2: Verify Installation

```bash
./verify-install.sh
```

**Verify:**
- [ ] All checks pass (✓ green checkmarks)
- [ ] No critical errors (✗ red X marks)
- [ ] Warnings resolved if any (⚠ yellow warnings)

### Step 3: Configure Environment

```bash
cp core/.env.example core/.env
cp neode-ui/.env.example neode-ui/.env
```

**Configuration:**
- [ ] `core/.env` file created
- [ ] `neode-ui/.env` file created
- [ ] Environment variables reviewed

### Step 4: Initialize Services

```bash
# Initialize Podman (if not done by script)
podman machine init
podman machine start

# Create database
createdb archipelago_dev
```

**Services:**
- [ ] Podman machine initialized
- [ ] Podman machine running
- [ ] PostgreSQL service running
- [ ] Development database created

### Step 5: Start Development Servers

**Terminal 1 - Backend:**
```bash
cd core
cargo run --bin archipelago
```

**Terminal 2 - Frontend:**
```bash
cd neode-ui
npm run dev
```

**Running:**
- [ ] Backend server started (port 5959)
- [ ] Frontend server started (port 8100)
- [ ] No errors in terminal output

### Step 6: Verify in Browser

Open: http://localhost:8100

**Browser:**
- [ ] Frontend loads successfully
- [ ] UI is responsive
- [ ] No console errors
- [ ] Can navigate pages

## Post-Installation

### Optional: Build Apps

```bash
cd apps
./build.sh
```

**Apps:**
- [ ] Apps built successfully
- [ ] Can install apps via UI
- [ ] Apps run correctly

### Optional: Setup Dev Tools

```bash
# Install cargo-watch for auto-reload
cargo install cargo-watch

# Add useful aliases to ~/.zshrc
```

**Dev Tools:**
- [ ] `cargo-watch` installed
- [ ] Aliases configured
- [ ] IDE/editor setup

## Troubleshooting Checklist

If something doesn't work:

- [ ] Run `./verify-install.sh`
- [ ] Check terminal error messages
- [ ] Verify all services are running:
  - [ ] PostgreSQL: `brew services list`
  - [ ] Podman: `podman machine list`
- [ ] Check ports are available:
  - [ ] Port 5959 (backend): `lsof -i :5959`
  - [ ] Port 8100 (frontend): `lsof -i :8100`
- [ ] Review [SETUP_GUIDE.md](SETUP_GUIDE.md)
- [ ] Check [QUICK_REFERENCE.md](QUICK_REFERENCE.md) troubleshooting

## Success Criteria

You're ready to develop when:

- [x] ✓ `rustc --version` works
- [x] ✓ `cargo --version` works
- [x] ✓ `node --version` shows v18+
- [x] ✓ `npm --version` works
- [x] ✓ `podman --version` works
- [x] ✓ `psql --version` works
- [x] ✓ Backend starts without errors
- [x] ✓ Frontend loads in browser
- [x] ✓ Can access http://localhost:8100

## Quick Commands Reference

```bash
# Verify installation
./verify-install.sh

# Start backend
cd core && cargo run --bin archipelago

# Start frontend
cd neode-ui && npm run dev

# Start with mock backend (no PostgreSQL needed)
cd neode-ui && npm run dev:mock

# Check service status
brew services list
podman machine list

# Build apps
cd apps && ./build.sh
```

## Documentation Checklist

Files to read:

- [ ] [GETTING_STARTED.md](GETTING_STARTED.md) - Quick start
- [ ] [README.md](README.md) - Project overview
- [ ] [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Commands
- [ ] [SETUP_GUIDE.md](SETUP_GUIDE.md) - Detailed setup
- [ ] [docs/development-setup.md](docs/development-setup.md) - Development
- [ ] [docs/architecture.md](docs/architecture.md) - Architecture
- [ ] [apps/QUICKSTART.md](apps/QUICKSTART.md) - Building apps

## Notes

Use this space to track any custom configuration or issues:

```
Date installed: _____________

Custom configuration:
- 
- 
- 

Issues encountered:
- 
- 
- 

Resolution:
- 
- 
- 
```

---

**Installation Complete?** Start developing! 🚀