mirror of
https://github.com/fusion44/blitz_api.git
synced 2026-08-13 11:52:45 +02:00
docs: README touch up
This commit is contained in:
fusion44
parent
1fdfd19c6f
commit
3764d7b4bf
1 changed files with 71 additions and 43 deletions
114
README.md
114
README.md
|
|
@ -1,9 +1,35 @@
|
|||
# blitz_api
|
||||
# Blitz API
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/pre-commit/pre-commit)
|
||||
|
||||
### Beta Disclaimer
|
||||
This software is still considered BETA. Don't expose it to the open internet or use with lots of funds.
|
||||
A management backend for bitcoin and lightning node operators written in Python with FastAPI.
|
||||
|
||||
## Beta Disclaimer
|
||||
This software is still considered BETA and may contain bugs. Don't expose it to the open internet or use with a lot of funds.
|
||||
|
||||
- [Blitz API](#blitz-api)
|
||||
- [Beta Disclaimer](#beta-disclaimer)
|
||||
- [Configuration](#configuration)
|
||||
- [Dependencies](#dependencies)
|
||||
- [Installation](#installation)
|
||||
- [Linux / macOS](#linux--macos)
|
||||
- [Windows](#windows)
|
||||
- [Run the application](#run-the-application)
|
||||
- [Linux / macOS](#linux--macos-1)
|
||||
- [Windows](#windows-1)
|
||||
- [Development](#development)
|
||||
- [Installation](#installation-1)
|
||||
- [Sync changes to a RaspiBlitz](#sync-changes-to-a-raspiblitz)
|
||||
- [Unit / Integration testing](#unit--integration-testing)
|
||||
- [Run the tests with pytest](#run-the-tests-with-pytest)
|
||||
- [Run tests and generate a coverage](#run-tests-and-generate-a-coverage)
|
||||
- [Client libraries](#client-libraries)
|
||||
- [Generating client libraries](#generating-client-libraries)
|
||||
- [Before you commit](#before-you-commit)
|
||||
- [Swagger / OpenAPI](#swagger--openapi)
|
||||
- [Useful cURL commands to test the API](#useful-curl-commands-to-test-the-api)
|
||||
- [Acknowledgements](#acknowledgements)
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
@ -18,7 +44,7 @@ Create a `.env` file with your `bitcoind` and `lnd` configuration. See the `.env
|
|||
|
||||
## Installation
|
||||
|
||||
:warning: To setup a development environment for BlitzAPI skip to the [Development](#Development) section.
|
||||
⚠️ To setup a development environment for BlitzAPI skip to the [Development](#Development) section.
|
||||
|
||||
### Linux / macOS
|
||||
|
||||
|
|
@ -70,26 +96,6 @@ poetry shell
|
|||
|
||||
(To exit the poetry shell use: `exit`)
|
||||
|
||||
## Development (RaspiBlitz Remote)
|
||||
|
||||
Create a file `/script/sync_to_blitz.personal.sh` (will be ignored by github) the SSH connection data to your RaspiBlitz.
|
||||
|
||||
localIP="192.168.178.61"
|
||||
sshPort="22"
|
||||
passwordA=""
|
||||
|
||||
Then you can run always `make sync_to_blitz` to copy your latest code over to your RaspiBlitz. The script automatically restarts the backend API with the new code on your RaspiBlitz and shows you the logs.
|
||||
|
||||
To test the backend API then call the SwaggerUI: `http://[LOCALIP]/api/v1/docs` - to call protected endpoints run the `/system/login` endpoint first with HTTP POST body:
|
||||
```
|
||||
{
|
||||
"password": "[PASSWORDA]"
|
||||
}
|
||||
```
|
||||
and then copy the JWT Auth string returned to `Authorize` in the top section of the SwaggerUI.
|
||||
|
||||
*You can also now test the RaspiBlitz WebUI against the API by running it locally on your dev laptop when you configure it to use the backend API of your RaspiBlitz.*
|
||||
|
||||
### Installation
|
||||
|
||||
```
|
||||
|
|
@ -109,30 +115,30 @@ If python dependencies have been changed it's necessary to freeze all requiremen
|
|||
poetry export -f requirements.txt --output requirements.txt
|
||||
```
|
||||
|
||||
> :information_source: This will skip all dev dependencies by default.\
|
||||
> ℹ️ This will skip all dev dependencies by default.\
|
||||
> This step is required to avoid having to install poetry for final deployment.
|
||||
|
||||
### Generating the client libraries
|
||||
### Sync changes to a RaspiBlitz
|
||||
|
||||
> ℹ️ The client library live in an extra repository:
|
||||
https://github.com/fusion44/blitz_api_client_libraries
|
||||
Create a file `/script/sync_to_blitz.personal.sh` (will be ignored by github) the SSH connection data to your RaspiBlitz.
|
||||
|
||||
Install [OpenAPI Generator](https://openapi-generator.tech) and Java:
|
||||
localIP="192.168.178.61"
|
||||
sshPort="22"
|
||||
passwordA=""
|
||||
|
||||
Then you can run always `make sync_to_blitz` to copy your latest code over to your RaspiBlitz. The script automatically restarts the backend API with the new code on your RaspiBlitz and shows you the logs.
|
||||
|
||||
```sh
|
||||
npm install @openapitools/openapi-generator-cli -g
|
||||
sudo apt install default-jre
|
||||
To test the backend API then call the SwaggerUI: `http://[LOCALIP]/api/v1/docs` - to call protected endpoints run the `/system/login` endpoint first with HTTP POST body:
|
||||
```
|
||||
|
||||
|
||||
Clone https://github.com/fusion44/blitz_api_client_libraries next to the blitz_api folder.
|
||||
|
||||
```sh
|
||||
make generate-client-libs
|
||||
{
|
||||
"password": "[PASSWORDA]"
|
||||
}
|
||||
```
|
||||
> ⚠️ The first run requires `sudo` as it must download a Java .jar file to the system npm package folder.
|
||||
### Testing
|
||||
and then copy the JWT Auth string returned to `Authorize` in the top section of the SwaggerUI.
|
||||
|
||||
*You can also now test the RaspiBlitz WebUI against the API by running it locally on your dev laptop when you configure it to use the backend API of your RaspiBlitz.*
|
||||
|
||||
### Unit / Integration testing
|
||||
|
||||
Make sure to include tests for important pieces of submitted code.
|
||||
|
||||
|
|
@ -150,11 +156,33 @@ make coverage
|
|||
|
||||
This will run tests and generate a coverage html file in this folder: `./htmlcov`
|
||||
|
||||
### Client libraries
|
||||
|
||||
> ℹ️ The client libraries live in an extra repository:
|
||||
https://github.com/fusion44/blitz_api_client_libraries
|
||||
|
||||
#### Generating client libraries
|
||||
Install [OpenAPI Generator](https://openapi-generator.tech) and Java:
|
||||
|
||||
|
||||
```sh
|
||||
npm install @openapitools/openapi-generator-cli -g
|
||||
sudo apt install default-jre
|
||||
```
|
||||
|
||||
|
||||
Clone https://github.com/fusion44/blitz_api_client_libraries next to the blitz_api folder.
|
||||
|
||||
```sh
|
||||
make generate-client-libs
|
||||
```
|
||||
> ⚠️ The first run requires `sudo` as it must download a Java .jar file to the system npm package folder.
|
||||
|
||||
### Before you commit
|
||||
|
||||
This project uses [pre-commit](https://pre-commit.com) to keep the source code structured. Please make sure to run either `make pre_commit` or `pre-commit run --all-files`. The CI pipeline will reject pull requests that fail this step. This step helps to ensures that the source code is formatted consistently and pull requests are as tidy as possible.
|
||||
|
||||
### [Swagger](https://swagger.io)
|
||||
### [Swagger / OpenAPI](https://swagger.io)
|
||||
|
||||
Once the API is running swagger docs can be found here:
|
||||
|
||||
|
|
@ -162,7 +190,7 @@ Once the API is running swagger docs can be found here:
|
|||
http://127.0.0.1:8000/latest/docs
|
||||
```
|
||||
|
||||
## Useful cURL commands to test the API
|
||||
### Useful cURL commands to test the API
|
||||
|
||||
```sh
|
||||
curl -N http://127.0.0.1:8000/sse/subscribe
|
||||
|
|
@ -183,7 +211,7 @@ curl --header "Content-Type: application/json" \
|
|||
http://127.0.0.1:8000/system/login
|
||||
```
|
||||
|
||||
### Acknowledgements
|
||||
## Acknowledgements
|
||||
|
||||
Integrated Libraries:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue