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

   • Mac: 4GB RAM minimum, 8GB recommended
   • Disk space: ~5GB for all images

2. Node.js 18+ - Download here

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

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

Step 3: Install UI Dependencies

cd neode-ui
npm install

Step 4: Start Everything

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 for the complete list.

Managing Apps

Start/Stop Individual Apps

# Stop an app
docker compose stop bitcoin

# Start an app
docker compose start bitcoin

# Restart an app
docker compose restart bitcoin

View Logs

# 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

docker compose ps

Stopping Everything

Stop All Apps

cd neode-ui
npm stop

This stops the UI and all Docker containers.

Stop Just Docker Apps

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

Remove All Data (Fresh Start)

docker compose down -v

Warning: This deletes all app data!

Troubleshooting

Docker not starting

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

docker system prune -a

Complete reset

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:

# 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 for details
4. Start building - The UI and backend are ready for development!

Common Tasks

Update all images

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

Backup data

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

Check resource usage

docker stats

See all containers

docker ps -a

Getting Help

• Documentation: See 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 for the full production architecture.

---

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