Initial commit

README.md

@@ -0,0 +1,87 @@
+# Bitcoin Core Admin Dashboard
+
+Web dashboard for operating and inspecting a Bitcoin Core node over RPC and SSH.
+
+## Features
+
+- Session-based dashboard login.
+- Persistent node settings in SQLite.
+- Live node summary cards and history charts.
+- RPC explorer with command catalog from node `help`.
+- Node control actions:
+  - stop via RPC
+  - start via SSH
+  - restart via RPC stop plus SSH start
+
+## Tech Stack
+
+- FastAPI + Jinja templates
+- Vanilla JavaScript + Chart.js
+- SQLite persistence
+- `requests` for JSON-RPC
+- `paramiko` for SSH control
+
+## Quick Start (Docker)
+
+1. Create environment file:
+
+```bash
+cp .env.example .env
+```
+
+2. Update at minimum:
+
+- `APP_USERNAME`
+- `APP_PASSWORD` or `APP_PASSWORD_HASH`
+- `SESSION_SECRET`
+
+3. Start:
+
+```bash
+docker compose up --build
+```
+
+4. Open:
+
+- `http://localhost:8080`
+
+## Quick Start (Local Python)
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+uvicorn app.main:app --reload --port 8080
+```
+
+## Runtime Notes
+
+- Settings and metrics history persist in `data/dashboard.db`.
+- Background metric sampling runs every `METRICS_SAMPLER_INTERVAL_SECONDS` (minimum 15 seconds).
+- Start and restart actions require working SSH configuration.
+
+## Docker RPC Connectivity Note
+
+If the dashboard runs in Docker and Bitcoin Core runs on the Docker host, use:
+
+- `http://{HOST_IP}:8332`
+
+Using `http://127.0.0.1:8332` inside the container points to the container itself.
+
+Make sure your node allows connections on that port from the Docker IP/Subnet
+
+## Documentation
+
+See the full documentation set in `doc/README.md`:
+
+- Architecture: `doc/architecture.md`
+- API reference: `doc/api.md`
+- Data models: `doc/data-models.md`
+- Build and deploy: `doc/build-and-deploy.md`
+- Environment config: `doc/environment.md`
+- Conventions: `doc/conventions.md`
+
+## Security
+
+- Use strong credentials and a random session secret.
+- Prefer password hash (`APP_PASSWORD_HASH`) over plaintext password.
+- Restrict dashboard network access to trusted operators.