# Bitcoin Core Admin Dashboard

Web dashboard for operating and inspecting a Bitcoin Core node over RPC and SSH.

![tellscoin avatar](assets/logo-avatar.png)

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