archy/INSTALLATION_CHECKLIST.md

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

./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

./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

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

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

cd core
cargo run --bin archipelago

Terminal 2 - Frontend:

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

cd apps
./build.sh

Apps:

• Apps built successfully
• Can install apps via UI
• Apps run correctly

Optional: Setup Dev Tools

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

Success Criteria

You're ready to develop when:

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

Quick Commands Reference

# 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 - Quick start
• README.md - Project overview
• QUICK_REFERENCE.md - Commands
• SETUP_GUIDE.md - Detailed setup
• docs/development-setup.md - Development
• docs/architecture.md - Architecture
• 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! 🚀