archy/GETTING_STARTED.md

# Getting Started with Archipelago Docker Development

This guide will help you get the full Archipelago development environment running with all apps containerized.

## What You'll Get

A complete Bitcoin node OS with 13+ apps running in Docker:
- Bitcoin Core (regtest - no blockchain download)
- Lightning Network (LND)
- BTCPay Server
- Mempool Explorer
- Home Assistant
- Grafana
- Ollama (local AI)
- SearXNG
- OnlyOffice
- Penpot
- And more...

## Prerequisites

1. **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop/)
   - Mac: 4GB RAM minimum, 8GB recommended
   - Disk space: ~5GB for all images

2. **Node.js 18+** - [Download here](https://nodejs.org/)

3. **Git** (you probably have this)

## Installation Steps

### Step 1: Start Docker Desktop

Make sure Docker Desktop is running:
- Mac: Look for the Docker icon in your menu bar
- If not running, open Docker Desktop from Applications

### Step 2: Clone and Setup

```bash
cd ~/Projects
git clone [your-repo] archy
cd archy
```

### Step 3: Install UI Dependencies

```bash
cd neode-ui
npm install
```

### Step 4: Start Everything

```bash
npm start
```

This will:
1. Check if Docker is running
2. Download all Docker images (first time only, ~10-30 minutes)
3. Start all containers
4. Start the development UI server

**First Time?** You'll be prompted to confirm the image download. Type `y` and press Enter.

### Step 5: Open the UI

Once everything starts, open your browser to:

**http://localhost:8100**

Navigate to "My Apps" to see all your apps running!

## What's Running?

After startup, you'll have these services:

### Bitcoin & Lightning Network
- **Bitcoin Core** - Full node in regtest mode (no mainnet sync)
- **LND** - Lightning Network daemon
- **BTCPay Server** - Accept Bitcoin payments
- **Mempool** - Blockchain explorer
- **Fedimint** - Federated Bitcoin mint

### Self-Hosted Apps
- **Home Assistant** - Home automation
- **Grafana** - Monitoring and analytics
- **SearXNG** - Private search engine
- **Ollama** - Run AI models locally

### Collaboration Tools
- **OnlyOffice** - Office suite (docs, spreadsheets, presentations)
- **Penpot** - Design and prototyping (like Figma)

### Placeholders
- **Endurain** - Coming soon
- **MorphOS** - Coming soon

## Using the Apps

### From the UI

1. Go to http://localhost:8100
2. Click "My Apps" in the sidebar
3. All apps are listed alphabetically
4. Click "Launch" on any running app

### Direct Access

All apps have unique ports:

| App | URL |
|-----|-----|
| Grafana | http://localhost:3000 |
| Home Assistant | http://localhost:8123 |
| SearXNG | http://localhost:8082 |
| Mempool | http://localhost:4080 |
| Penpot | http://localhost:9001 |
| OnlyOffice | http://localhost:8083 |
| BTCPay Server | http://localhost:14142 |

See [DOCKER_DEV_SETUP.md](DOCKER_DEV_SETUP.md) for the complete list.

## Managing Apps

### Start/Stop Individual Apps

```bash
# Stop an app
docker compose stop bitcoin

# Start an app
docker compose start bitcoin

# Restart an app
docker compose restart bitcoin
```

### View Logs

```bash
# All logs
docker compose logs -f

# Specific app
docker compose logs -f bitcoin
docker compose logs -f btcpay
docker compose logs -f lnd
```

### Check Status

```bash
docker compose ps
```

## Stopping Everything

### Stop All Apps

```bash
cd neode-ui
npm stop
```

This stops the UI and all Docker containers.

### Stop Just Docker Apps

```bash
cd ..  # Go to project root
./stop-docker-apps.sh
```

### Remove All Data (Fresh Start)

```bash
docker compose down -v
```

**Warning:** This deletes all app data!

## Troubleshooting

### Docker not starting

```bash
# Check if Docker is running
docker ps

# If not, start Docker Desktop
open -a Docker
```

### Port conflicts

If you see port errors:
1. Check what's using the port: `lsof -i :PORT`
2. Stop that service or change the port in `docker-compose.yml`

### App won't load

1. Check if container is running: `docker compose ps`
2. View logs: `docker compose logs [app-name]`
3. Restart the container: `docker compose restart [app-name]`

### Out of disk space

Clean up Docker:

```bash
docker system prune -a
```

### Complete reset

```bash
cd neode-ui
npm stop
cd ..
docker compose down -v
docker system prune -a
cd neode-ui
npm start
```

## Development Tips

### Making Changes

The UI hot-reloads automatically. Just edit files in `neode-ui/src/` and refresh your browser.

### Testing Bitcoin Stuff

Bitcoin Core runs in regtest mode - you can generate blocks instantly:

```bash
# Get a new address
docker exec archy-bitcoin bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass getnewaddress

# Generate blocks to that address
docker exec archy-bitcoin bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass generatetoaddress 101 [address]
```

### Using Lightning

LND connects to Bitcoin Core automatically. Access the REST API at http://localhost:8080.

### Adding New Apps

1. Add service to `docker-compose.yml`
2. Add entry to `neode-ui/src/utils/dummyApps.ts`
3. Restart: `npm stop && npm start`

## File Structure

```
archy/
├── docker-compose.yml          # All app definitions
├── start-docker-apps.sh        # Start all Docker apps
├── stop-docker-apps.sh         # Stop all Docker apps
├── DOCKER_DEV_SETUP.md         # Detailed documentation
├── docker/                     # Placeholder app HTML
│   ├── endurain-placeholder/
│   └── morphos-placeholder/
└── neode-ui/                   # Vue.js UI
    ├── package.json
    ├── start-dev.sh            # Main dev startup (npm start)
    ├── stop-dev.sh             # Stop everything (npm stop)
    └── src/
        ├── views/Apps.vue      # My Apps page
        └── utils/dummyApps.ts  # App definitions
```

## Next Steps

1. **Explore the apps** - Try opening different services
2. **Check the logs** - See what's happening: `docker compose logs -f`
3. **Read the docs** - See [DOCKER_DEV_SETUP.md](DOCKER_DEV_SETUP.md) for details
4. **Start building** - The UI and backend are ready for development!

## Common Tasks

### Update all images

```bash
cd ~/Projects/archy
docker compose pull
docker compose up -d
```

### Backup data

```bash
docker compose down
cp -r /var/lib/docker/volumes ~/docker-backup
```

### Check resource usage

```bash
docker stats
```

### See all containers

```bash
docker ps -a
```

## Getting Help

- **Documentation**: See [DOCKER_DEV_SETUP.md](DOCKER_DEV_SETUP.md)
- **Logs**: `docker compose logs -f [service-name]`
- **Status**: `docker compose ps`
- **Docker issues**: Check Docker Desktop logs

## Architecture

This setup mimics production as closely as possible:

- **Production**: Alpine Linux + Podman + Real apps
- **Development**: macOS/Linux + Docker + Same app images

Key differences:
- Bitcoin in regtest (no blockchain sync)
- All on localhost (no Tor)
- Simpler networking (single bridge network)

See [Architecture.md](.cursor/rules/Architecture.mdc) for the full production architecture.

---

**Ready to build a Bitcoin node OS? Start with `npm start`! 🚀**