# Archipelago Docker Development Environment

This setup provides a complete development environment with all apps running in Docker containers, mimicking the production environment as closely as possible.

## Overview

All apps from the "My Apps" page are prepackaged and run as Docker containers:

- **Bitcoin Core** (regtest mode - no blockchain sync)
- **BTCPay Server** (Bitcoin payment processor)
- **Endurain** (placeholder)
- **Fedimint** (federated Bitcoin mint)
- **Grafana** (monitoring/analytics)
- **Home Assistant** (home automation)
- **Lightning Stack** (LND - Lightning Network)
- **Mempool** (blockchain explorer)
- **MorphOS Server** (placeholder)
- **Ollama** (local LLM)
- **OnlyOffice** (office suite)
- **Penpot** (design platform)
- **SearXNG** (privacy-respecting search)

## Quick Start

### Prerequisites

- Docker Desktop installed and running
- Node.js 18+ installed
- ~4GB of free disk space for Docker images

### Starting Development Environment

From the `neode-ui` directory:

```bash
npm start
```

This will:
1. Check and start Docker Desktop if needed
2. Start all Docker containers with apps
3. Start the mock backend API server (port 5959)
4. Start the Vite dev server (port 8100)

### Stopping Everything

From the `neode-ui` directory:

```bash
npm stop
```

This stops all Node processes and Docker containers.

## Manual Docker Control

### Start all Docker apps

```bash
./start-docker-apps.sh
```

### Stop all Docker apps

```bash
./stop-docker-apps.sh
```

### View logs for a specific app

```bash
docker compose logs -f [service-name]

# Examples:
docker compose logs -f bitcoin
docker compose logs -f btcpay
docker compose logs -f lnd
```

### Restart a specific app

```bash
docker compose restart [service-name]
```

### View all running containers

```bash
docker compose ps
```

## App URLs

All apps are accessible on localhost with unique ports:

| App | URL | Notes |
|-----|-----|-------|
| Bitcoin Core | http://localhost:18443 | RPC only (regtest) |
| BTCPay Server | http://localhost:14142 | Full UI |
| Endurain | http://localhost:8084 | Placeholder |
| Fedimint | http://localhost:8173 | API |
| Grafana | http://localhost:3000 | UI (admin/admin) |
| Home Assistant | http://localhost:8123 | Full UI |
| Lightning (REST) | http://localhost:8080 | REST API |
| Lightning (gRPC) | localhost:10009 | gRPC |
| Mempool | http://localhost:4080 | Full UI |
| MorphOS | http://localhost:8081 | Placeholder |
| Ollama | http://localhost:11434 | API |
| OnlyOffice | http://localhost:8083 | Full UI |
| Penpot | http://localhost:9001 | Full UI |
| SearXNG | http://localhost:8082 | Full UI |

## Architecture

### Docker Compose Structure

The `docker-compose.yml` file orchestrates all services:

- **Networking**: All services run on a shared `archy-net` bridge network
- **Volumes**: Persistent data stored in Docker volumes
- **Dependencies**: Services with dependencies (e.g., BTCPay depends on Bitcoin Core) start in the correct order

### Bitcoin & Lightning

- **Bitcoin Core** runs in regtest mode (no mainnet/testnet sync)
- **LND** connects to Bitcoin Core for Lightning functionality
- Both are pre-configured to work together without blockchain sync
- Generate test blocks with: `docker exec archy-bitcoin bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass generatetoaddress 101 <address>`

### Database Services

Some apps require databases:
- BTCPay Server → PostgreSQL
- Mempool → MariaDB
- Penpot → PostgreSQL + Redis

These are automatically started as supporting services.

## Development Workflow

### Starting Development

```bash
cd neode-ui
npm start
```

The UI will be available at http://localhost:8100

### Testing App Launch

1. Open http://localhost:8100 in your browser
2. Navigate to "My Apps"
3. Apps appear alphabetically and stay in order regardless of state
4. Click "Launch" on any running app to open it in a new tab

### Stop/Start Apps

Use the UI buttons or manually:

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

# Start an app
docker compose start bitcoin

# Restart an app
docker compose restart bitcoin
```

### Viewing Logs

Monitor app logs:

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

# Specific app
docker compose logs -f bitcoin

# Last 50 lines
docker compose logs --tail=50 bitcoin
```

### Resetting Data

Remove all app data and start fresh:

```bash
./stop-docker-apps.sh
docker compose down -v  # Remove volumes
./start-docker-apps.sh
```

## Configuration

### Bitcoin Core (Regtest)

Configuration is in `docker-compose.yml`:
- RPC user: `bitcoin`
- RPC password: `bitcoinpass`
- Ports: 18443 (RPC), 18444 (P2P)

### Grafana

Default credentials:
- Username: `admin`
- Password: `admin`

### App Icons

Icons are loaded from `/assets/img/app-icons/` in the UI.

## Troubleshooting

### Docker not starting

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

# Start Docker Desktop manually
open -a Docker
```

### Port conflicts

If a port is already in use, modify `docker-compose.yml`:

```yaml
services:
  bitcoin:
    ports:
      - "18443:18443"  # Change left side to a free port
```

### App won't start

Check logs:

```bash
docker compose logs [service-name]
```

Restart the container:

```bash
docker compose restart [service-name]
```

### Out of disk space

Clean up unused Docker data:

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

### Reset everything

```bash
npm stop
docker compose down -v
docker system prune -a
npm start
```

## Production vs Development

### Development

- Bitcoin Core in regtest (no blockchain)
- LND without real channels
- All services on localhost
- Placeholder apps for unimplemented services

### Production (Future)

- Bitcoin Core syncing mainnet
- LND with real Lightning channels
- Services behind reverse proxy
- All apps fully functional
- Tor integration
- Hardware security

## Next Steps

- Implement real start/stop functionality in the UI
- Connect backend API to Docker API
- Add health checks and status monitoring
- Implement backup/restore for Docker volumes
- Add app configuration UI
- Integrate with Tor for privacy

## Resources

- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Bitcoin Core Documentation](https://bitcoin.org/en/bitcoin-core/)
- [LND Documentation](https://docs.lightning.engineering/)
- [BTCPay Server Documentation](https://docs.btcpayserver.org/)