archy/DOCKER_DEV_SETUP.md

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:

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:

npm stop

This stops all Node processes and Docker containers.

Manual Docker Control

Start all Docker apps

./start-docker-apps.sh

Stop all Docker apps

./stop-docker-apps.sh

View logs for a specific app

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

docker compose restart [service-name]

View all running containers

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

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:

# 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:

# 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:

./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

# 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:

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

App won't start

Check logs:

docker compose logs [service-name]

Restart the container:

docker compose restart [service-name]

Out of disk space

Clean up unused Docker data:

docker system prune -a --volumes

Reset everything

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
• Bitcoin Core Documentation
• LND Documentation
• BTCPay Server Documentation