Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bitcoin-balancer/cli

The CLI is a robust command-line interface designed to streamline the development/management of Balancer's infrastructure and internal operations.
https://github.com/bitcoin-balancer/cli

automated bitcoin bitcoin-spot-market bitcoin-trading bitcoin-trading-strategy self-hosted spot spot-market strategy trading trading-strategy

Last synced: 3 days ago
JSON representation

The CLI is a robust command-line interface designed to streamline the development/management of Balancer's infrastructure and internal operations.

Awesome Lists containing this project

README 

        
# `cli`



The `cli` is a robust command-line interface designed to streamline the development and management of Balancer’s infrastructure and internal operations. It enables you to:



* **Automate infrastructure tasks** – Effortlessly handle provisioning, scaling, and monitoring

* **Execute development actions** – Run tests, deploy updates, and manage code dependencies with ease

* **Administer databases** – Back up, restore, and maintain your database efficiently

* **Secure remote access** – Interact with production servers via secure SSH connections

* **And more!**



With its intuitive syntax and comprehensive functionality, the `cli` simplifies complex workflows, enhances efficiency, and ensures consistent project management.



**Note:** If you’re not actively developing Balancer or only need basic infrastructure management, consider using [`cli-lite`](https://github.com/bitcoin-balancer/cli-lite) for a more streamlined experience.









## Requirements



### Software



- UNIX-like OS

- git `^v2.43.0`

- Node.js `^v22.11.0`

- npm `^v10.9.0`

- Docker Engine `^v27.3.1`

- Docker Compose `^v2.29.7`



### Hardware (Remote Host)



- 1 CPU

- 512 GB Memory

- 10 GB Storage









## Getting Started



1. [Set up your remote host](./docs/remote-host/index.md)

2. [Set up your environment variables](./docs/environment-variables/index.md)

3. [Download and build the CLI](./docs/download-build-cli/index.md)

4. [Deploy the CLI to the Remote Host](./docs/deploy-cli/index.md)

5. [Build and run Balancer](./docs/build-run-balancer/index.md)









## Guides



- [Remote Host Configuration](./docs/remote-host/index.md)

- [Environment Variables](./docs/environment-variables/index.md)

- [Cloudflare Tunnel Integration (Optional)](./docs/cloudflare-tunnel/index.md)

- [Telegram Integration (Optional)](./docs/telegram/index.md)









## CLI Actions



### Host



  connect

  


  Establishes a SSH Connection with the remote host.



  ```bash

  ssh root@ip

  ```

  



  landscape-sysinfo

  


  Executes the landscape-sysinfo binary and prints its results.



  ```bash

  ssh root@ip landscape-sysinfo

  ```

  



  reboot

  


  Reboots the remote host after stopping containers and removing containers, networks, volumes, and images created by up.



  ```bash

  ssh root@ip reboot

  ```

  



  shutdown

  


  Shuts down the remote host after stopping containers and removing containers, networks, volumes, and images created by up.



  ```bash

  ssh root@ip poweroff

  ```

  



  ssh-copy-id

  


  Copies the SSH Public Key specified in the config file into the remote server.



  ```bash

  ssh-copy-id root@ip

  ```

  







### Docker Compose



  up

  


  Builds, (re)creates, starts, and attaches to containers for a service. An optional variation can be provided in order to generate the custom compose.yaml file and start the containers in the chosen mode.



  



  When executed on the local host, it runs:

  ```bash

  docker compose up --detach

  ```



  



  In contrast, when executed on the remote host, it always pulls the latest images from the registry (Docker Hub):

  ```bash

  docker compose up --pull always --no-build --detach

  ```



  


  The following variations are supported:



  - up:restore-mode used to restore a database backup that was generated in the past



  



  build-up

  


  Builds all the images and starts the containers. An optional variation can be provided in order to generate the custom compose.yaml file and start the containers in the chosen mode.



  



  When executed on the local host, it runs:

  ```bash

  docker compose up --build --detach

  ```



  



  When executed on the remote host, it firstly removes all unused containers, networks and images (both dangling and unused).



  ```bash

  docker system prune --all --force

  ```

  



  Then, it restarts the Docker Service:



  ```bash

  systemctl restart docker

  ```

  



  Finally, it pulls the latest images from the registry (Docker Hub):

  ```bash

  docker compose up --pull always --no-build --detach

  ```



  


  The following variations are supported:



  - build-up:restore-mode used to restore a database backup that was generated in the past



  



  prune-build-push

  


  Removes all unused containers, networks and images (both dangling and unused).



  ```bash

  docker system prune --all --force

  ```

  



  Then, it builds all the images and pushes them to the registry (Docker Hub).



  ```bash

  docker compose build --push

  ```

  



  down

  


  Stops containers and removes containers, networks, volumes, and images created by up.



  ```bash

  docker compose down

  ```

  



  down-build-up

  


  Stops containers and removes containers, networks, volumes, and images created by up.



  ```bash

  docker compose down

  ```



  



  Afterwards, it builds, (re)creates, starts, and attaches to containers for a service. An optional variation can be provided in order to generate the custom compose.yaml file and start the containers in the chosen mode.



  When executed on the local host, it runs:

  ```bash

  docker compose up --detach

  ```



  In contrast, when executed on the remote host, it always pulls the latest images from the registry (Docker Hub):

  ```bash

  docker compose up --pull always --no-build --detach

  ```

  



  restart

  


  Restarts all stopped and running services.



  ```bash

  docker compose restart

  ```

  



  logs

  


  Displays log output from all services. If a variation is provided, it narrows down the logs to a specific service.



  ```bash

  docker compose logs -f



  # if a variation is provided

  docker compose logs  -f

  ```



  



  The following variations are supported:



  - logs:postgres displays log output from the postgres service



  - logs:api displays log output from the api service



  - logs:gui displays log output from the gui service



  - logs:ct displays log output from the cloudflared service

  



  prune

  


  Removes all unused containers, networks and images (both dangling and unused).



  ```bash

  docker system prune --all --force

  ```

  







### Docker Compose Tests



  up:test-mode

  


  Builds, (re)creates, starts, and attaches to containers for a service with TEST_MODE enabled (used to run unit, integration or benchmark tests locally):

  

  ```bash

  docker compose up --detach

  ```



  



  build-up:test-mode

  


  Builds all the images and starts the containers with TEST_MODE enabled (used to run unit, integration or benchmark tests locally):



  ```bash

  docker compose up --build --detach

  ```



  



  down

  


  Stops containers and removes containers, networks, volumes, and images created by up.



  ```bash

  docker compose down

  ```

  



  down-build-up:test-mode

  


  Stops containers and removes containers, networks, volumes, and images created by up.



  ```bash

  docker compose down

  ```



  



  Afterwards, it builds all the images and starts the containers with TEST_MODE enabled (used to run unit, integration or benchmark tests locally):



  ```bash

  docker compose up --build --detach

  ```



  



  api-test:$type

  


  Runs the automated tests on the api service for the chosen variation.



  ```bash

  npm run test:

  ```



  


  The following variations are supported:



  - api-test:integration runs the integration tests in the api service



  - api-test:unit runs the unit tests in the api service



  - api-test:bench runs the benchmarks in the api service

  







### CLI Management



  build-cli

  


  Executes the script to generate a build of the CLI straight from the source code.



  ```bash

  npm run build

  ```

  



  build-deploy-cli

  


  Deploys the CLI from its source in the local host to the remote host.



  Firstly, it creates the root directory (if it doesn't already exist):



  ```bash

  ssh root@ip mkdir -p cli

  ```



  



  Then, it deploys the source code files and lastly, it installs the dependencies:



  ```bash

  ssh root@ip cd cli && npm ci --omit=dev

  ```

  







### Database Management



  psql

  


  Start the terminal-based front-end to PostgreSQL



  ```bash

  docker compose exec -it postgres psql -U postgres

  ```



  



  backup-db

  


  Generates a database backup file, pulls it to the local host and performs a clean up once complete.



  



  Firstly, it generates a backup file ($TIMESTAMP.dump) and places it in the balancer_pgdata-management volume.



  ```bash

  docker compose exec postgres pg_dump -U postgres -f /var/lib/pgdata-management/$TIMESTAMP.dump -Fc

  ```



  



  Next, it pulls the backup file from the remote host to a specified destination directory in the localhost:



  ```bash

  scp root@ip:/var/lib/docker/volumes/balancer_pgdata-management/_data/$TIMESTAMP.dump /localhost/dest/dir

  ```



  


  

  Finally, it cleans up the balancer_pgdata-management volume:



  ```bash

  ssh root@ip rm -f /var/lib/docker/volumes/balancer_pgdata-management/_data/$TIMESTAMP.dump

  ```

  



  restore-db

  


  Restores a chosen backup file after cleaning the current state of the database and performs a clean up once complete.



  



  Firstly, it pushes the chosen backup file ($TIMESTAMP.dump) into the balancer_pgdata-management volume.



  ```bash

  scp /localhost/src/$TIMESTAMP.dump root@ip:/var/lib/docker/volumes/balancer_pgdata-management/_data/$TIMESTAMP.dump

  ```



  



  Next, it restores the database by making use of the backup file:



  ```bash

  docker compose exec postgres pg_restore --clean --if-exists -U postgres -d postgres /var/lib/pgdata-management/$TIMESTAMP.dump

  ```



  


  

  Finally, it cleans up the balancer_pgdata-management volume:



  ```bash

  ssh root@ip rm -f /var/lib/docker/volumes/balancer_pgdata-management/_data/$TIMESTAMP.dump

  ```

  







### Environment Variable Assets



  generate-envvar-assets

  


  

  Generates the environment variable assets based on a source file and places the results in a custom path.



  



  deploy-envvar-assets

  


  Deploys the environment variable assets to the remote host from a custom source path.



  **Note:** assets are generated by the generate-envvar-assets action.



  ```bash

  scp -r ./assets/secrets root@ip:cli/secrets

  scp ./assets/.env root@ip:cli/.env

  # assets/

  #     │

  #     secrets/

  #     │     └───...

  #     .env

  ```



  









## Docker Images



- [postgres](https://hub.docker.com/_/postgres)

- [jesusgraterol/balancer-api](https://hub.docker.com/r/jesusgraterol/balancer-api)

- [jesusgraterol/balancer-gui](https://hub.docker.com/r/jesusgraterol/balancer-gui)

- [jesusgraterol/balancer-ct](https://hub.docker.com/r/jesusgraterol/balancer-ct)









## Tests



```bash

# run the integration tests

npm run test:integration



# run the unit tests

npm run test:unit



# run the benchmarks

npm run test:bench

```









## License



[Apache v2.0](https://www.apache.org/licenses/LICENSE-2.0)