generated from nathanwoodburn/python-webserver-template
feat: Add README
This commit is contained in:
163
README.md
163
README.md
@@ -1,19 +1,154 @@
|
|||||||
# Python Flask Webserver Template
|
# Fire Explorer
|
||||||
|
|
||||||
Python3 website template including git actions
|
Fire Explorer is a Flask-based Handshake blockchain explorer UI and API.
|
||||||
|
It provides searchable views for blocks, transactions, addresses, and names, plus utility endpoints for namehash resolution, HIP-02 lookup, and covenant display rendering.
|
||||||
|
|
||||||
# Development
|
## Features
|
||||||
1. Install requirements
|
|
||||||
```bash
|
- Search Handshake data by block, header, transaction, address, and name.
|
||||||
python3 -m pip install -r requirements.txt
|
- Route-based deep links such as `/tx/<hash>` and `/block/<height-or-hash>`.
|
||||||
```
|
- Dynamic Open Graph card generation at `/og-image` and `/og-image.png`.
|
||||||
2. Run the dev server
|
- HIP-02 and WALLET DNS record resolution endpoint.
|
||||||
```bash
|
- SQLite namehash cache to reduce repeated upstream lookups.
|
||||||
python3 server.py
|
- Single-container deployment flow with Docker.
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- Python 3.13+
|
||||||
|
- Flask
|
||||||
|
- Gunicorn (started programmatically via `main.py`)
|
||||||
|
- SQLite (local cache DB)
|
||||||
|
- Pillow (OG image rendering)
|
||||||
|
- Requests and DNS tooling for Handshake integrations
|
||||||
|
|
||||||
|
## Project Layout
|
||||||
|
|
||||||
|
```text
|
||||||
|
.
|
||||||
|
|- main.py # Gunicorn entrypoint
|
||||||
|
|- server.py # Flask app, routes, API, OG generation
|
||||||
|
|- tools.py # HIP-02 and DNS helper functions
|
||||||
|
|- templates/ # HTML templates + static assets
|
||||||
|
|- pyproject.toml # Project metadata and dependencies (uv)
|
||||||
|
|- requirements.txt # Exported lock-style requirements
|
||||||
|
|- Dockerfile # Container build and runtime setup
|
||||||
```
|
```
|
||||||
|
|
||||||
# Production
|
## Prerequisites
|
||||||
Run using the main.py file
|
|
||||||
|
- Python 3.13 or newer
|
||||||
|
- `uv` (recommended) or `pip`
|
||||||
|
- OpenSSL CLI available in PATH (required for HIP-02 certificate checks in `tools.py`)
|
||||||
|
|
||||||
|
## Local Development
|
||||||
|
|
||||||
|
### Option 1: `uv` (recommended)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 main.py
|
uv sync
|
||||||
```
|
uv run main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
The app binds to `0.0.0.0:5000` when started through `main.py`.
|
||||||
|
|
||||||
|
### Option 2: `pip`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m venv .venv
|
||||||
|
# Linux/macOS
|
||||||
|
source .venv/bin/activate
|
||||||
|
# Windows (PowerShell)
|
||||||
|
# .venv\Scripts\Activate.ps1
|
||||||
|
|
||||||
|
pip install -r requirements.txt
|
||||||
|
python main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### Flask debug mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python server.py
|
||||||
|
```
|
||||||
|
|
||||||
|
This runs Flask's built-in development server at `127.0.0.1:5000`.
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
Configure via shell variables or a `.env` file.
|
||||||
|
|
||||||
|
- `WORKERS`
|
||||||
|
: Gunicorn worker count. Default: `1`.
|
||||||
|
- `THREADS`
|
||||||
|
: Gunicorn thread count per worker. Default: `2`.
|
||||||
|
- `DATABASE_PATH`
|
||||||
|
: SQLite file path for the namehash cache. Default: `fireexplorer.db`.
|
||||||
|
- `HSD_API_BASE`
|
||||||
|
: Upstream Handshake API base URL. Default: `https://hsd.hns.au/api/v1`.
|
||||||
|
- `PUBLIC_BASE_URL`
|
||||||
|
: Optional canonical public URL used for OG metadata generation.
|
||||||
|
|
||||||
|
## Docker
|
||||||
|
|
||||||
|
Build:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t fireexplorer .
|
||||||
|
```
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run --rm -p 5000:5000 -v fireexplorer-data:/data fireexplorer
|
||||||
|
```
|
||||||
|
|
||||||
|
Container notes:
|
||||||
|
|
||||||
|
- The image runs `uv run main.py`.
|
||||||
|
- The default database path is set to `/data/fireexplorer.db`.
|
||||||
|
- A volume is declared at `/data` for persistence.
|
||||||
|
|
||||||
|
## HTTP Routes
|
||||||
|
|
||||||
|
### UI routes
|
||||||
|
|
||||||
|
- `/`
|
||||||
|
- `/block/<block_id>`
|
||||||
|
- `/header/<block_id>`
|
||||||
|
- `/tx/<tx_hash>`
|
||||||
|
- `/address/<address>`
|
||||||
|
- `/name/<name>`
|
||||||
|
- `/coin/<coin_hash>/<index>`
|
||||||
|
- `/og-image`
|
||||||
|
- `/og-image.png`
|
||||||
|
|
||||||
|
### API routes
|
||||||
|
|
||||||
|
- `GET /api/v1/status`
|
||||||
|
: Service health and local cache stats.
|
||||||
|
- `GET /api/v1/namehash/<namehash>`
|
||||||
|
: Resolves namehash to name (cached in SQLite).
|
||||||
|
- `GET /api/v1/hip02/<domain>`
|
||||||
|
: Resolves HIP-02, falls back to WALLET TXT-style record lookup.
|
||||||
|
- `POST /api/v1/covenant`
|
||||||
|
: Accepts one covenant object or an array and returns display-ready covenant labels, including cached name resolution.
|
||||||
|
|
||||||
|
## Development Tooling
|
||||||
|
|
||||||
|
Pre-commit config includes:
|
||||||
|
|
||||||
|
- `uv-lock`
|
||||||
|
- `uv-export`
|
||||||
|
- `ruff-check`
|
||||||
|
- `ruff-format`
|
||||||
|
|
||||||
|
Run hooks locally:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pre-commit run --all-files
|
||||||
|
```
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Frontend requests blockchain data from `https://hsd.hns.au/api/v1/`.
|
||||||
|
- Namehash mappings are cached locally in SQLite to improve repeated lookups.
|
||||||
|
- HIP-02 resolution requires DNS-over-HTTPS access and OpenSSL availability.
|
||||||
|
|||||||
Reference in New Issue
Block a user