217 lines
4.1 KiB
Markdown
217 lines
4.1 KiB
Markdown
|
# 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! 🚀
|