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 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 Shared CPU
• 1 GB Memory
• 25 GB Storage (Regular SSD)

Getting Started

1. Set up your remote host
2. Set up your environment variables
3. Download and build the CLI
4. Deploy the CLI to the Remote Host
5. Build and run Balancer

Guides

• Remote Host Configuration
• Environment Variables
• Cloudflare Tunnel Integration (Production)
• Telegram Integration (Optional)

CLI Actions

Host

connect

Establishes a SSH Connection with the remote host.

ssh root@ip

landscape-sysinfo

Executes the landscape-sysinfo binary and prints its results.

ssh root@ip landscape-sysinfo

reboot

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

ssh root@ip reboot

shutdown

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

ssh root@ip poweroff

ssh-copy-id

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

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:

docker compose up --detach

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

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:

docker compose up --build --detach

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

docker system prune --all --force

Then, it restarts the Docker Service:

systemctl restart docker

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

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

docker system prune --all --force

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

docker compose build --push

down

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

docker compose down

down-build-up

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

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:

docker compose up --detach

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

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

restart

Restarts all stopped and running services.

docker compose restart

logs

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

docker compose logs -f

# if a variation is provided
docker compose logs <variation> -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).

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):

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):

docker compose up --build --detach

down

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

docker compose down

down-build-up:test-mode

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

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):

docker compose up --build --detach

api-test:$type

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

npm run test:<variation>

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.

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):

ssh root@ip mkdir -p cli

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

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

Database Management

psql

Start the terminal-based front-end to PostgreSQL

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.

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:

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:

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.

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:

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:

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.

scp -r ./assets/secrets root@ip:cli/secrets
scp ./assets/.env root@ip:cli/.env
# assets/
#     │
#     secrets/
#     │     └───...
#     .env

Docker Images

• postgres
• jesusgraterol/balancer-api
• jesusgraterol/balancer-gui
• jesusgraterol/balancer-ct

Tests

# 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