10fa19df66
- Revamped GETTING_STARTED.md for clarity and completeness, detailing the Docker development environment and installation steps. - Updated Cargo.lock and Cargo.toml to replace deprecated dependencies and add new ones, including hyper-ws-listener and env_logger. - Improved WebSocket handling in the API to support upgrades and error management. - Enhanced Neode UI scripts to manage Docker containers during development. - Adjusted dummy app configurations for accurate LAN addresses. - Sorted app entries in the UI for better organization and accessibility.
303 lines
6.2 KiB
Markdown
303 lines
6.2 KiB
Markdown
# 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/)
|