0d073fa89e
- Add GETTING_STARTED.md with quick start guide and development modes - Add INSTALL.sh automated installation script - Add INSTALLATION_CHECKLIST.md, INSTALLATION_SUCCESS.md, and INSTALLATION_SUMMARY.md - Add QUICK_REFERENCE.md for common commands - Add SETUP_GUIDE.md with detailed setup instructions - Update README.md with improved project overview - Add did-wallet app dependencies and node_modules
279 lines
7.7 KiB
Markdown
279 lines
7.7 KiB
Markdown
# 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
|