# Container Network Topology

## Networks

### archy-net (bridge)
Shared network for Bitcoin ecosystem containers that need DNS-based service discovery.

| Container | Connects To | Why |
|-----------|-------------|-----|
| bitcoin-knots | - | Core Bitcoin node |
| lnd | bitcoin-knots:8332 | Lightning requires Bitcoin RPC |
| mempool-electrs | bitcoin-knots:8332 | Electrum indexer reads blocks |
| mempool-api | mempool-electrs:50001, archy-mempool-db | API queries electrs + MySQL |
| archy-mempool-web | mempool-api (upstream) | Frontend proxies to API |
| archy-mempool-db | - | MySQL for mempool |
| archy-btcpay-db | - | PostgreSQL for BTCPay + nbxplorer |
| archy-nbxplorer | archy-btcpay-db:5432 | Block explorer indexes into Postgres |
| btcpay-server | archy-btcpay-db:5432, archy-nbxplorer:32838 | Payment server |
| fedimint | bitcoin-knots:8332 | Federated mint needs Bitcoin |
| fedimint-gateway | bitcoin-knots:8332, lnd:10009 | Lightning gateway |

### immich-net (bridge)
Isolated network for Immich photo management stack.

| Container | Connects To | Why |
|-----------|-------------|-----|
| immich_postgres | - | PostgreSQL for Immich |
| immich_redis | - | Cache for Immich |
| immich_server | immich_postgres, immich_redis | Main Immich app |

### penpot-net (bridge)
Isolated network for Penpot design tool stack.

| Container | Connects To | Why |
|-----------|-------------|-----|
| penpot-postgres | - | PostgreSQL for Penpot |
| penpot-valkey | - | Cache (Redis-compatible) |
| penpot-backend | penpot-postgres, penpot-valkey | API server |
| penpot-exporter | penpot-backend | PDF/SVG renderer |
| penpot-frontend | penpot-backend | UI server |

### host network
Containers that need direct host network access.

| Container | Why |
|-----------|-----|
| tailscale | VPN requires NET_ADMIN + host networking |
| archy-electrs-ui | Static status page served on host port 50002 |

### podman (default bridge)
Standalone containers with no inter-container dependencies.

| Container | Exposed Port |
|-----------|-------------|
| homeassistant | 8123 |
| grafana | 3000 |
| uptime-kuma | 3001 |
| jellyfin | 8096 |
| photoprism | 2342 |
| dwn | 3100 |
| ollama | 11434 |
| vaultwarden | (dynamic) |
| nextcloud | (dynamic) |
| searxng | 8888 |
| nginx-proxy-manager | 81 |
| portainer | 9000 |
| filebrowser | 8083 |
| archy-bitcoin-ui | 8082 |
| archy-lnd-ui | 8081 |
| nostr-rs-relay | 8080 |

## Known Issues (2026-03-14)

1. **fedimint/fedimint-gateway on wrong network (.198)**: Should be on archy-net but are on default podman network. Fixed by reconnecting.
2. **penpot incomplete (.198)**: penpot-frontend and penpot-backend containers missing. Only postgres, valkey, and exporter exist.
3. **.228 unreachable**: Cannot audit .228 network topology — SSH/HTTP ports closed.

## Code References

- Network assignment: `core/archipelago/src/api/rpc/package.rs` (`needs_archy_net` match)
- First-boot creation: `scripts/first-boot-containers.sh`
- Health monitor exclusions: `core/archipelago/src/health_monitor.rs`