smart-apps production

DBA Pilot Remote Agent Setup Guide

Install, upgrade, verify and troubleshoot the remote agent against the smart-apps Hub. The agent runs next to your database and connects outbound to the Hub only — the Hub never connects to your database, and the database host never needs inbound access.

Hub: https://dba.smart-apps.in Agent release: 0.1.27

Which install mode?

Two modes are supported. Standalone is the default and the one most installs should use.

Recommended

Standalone

Installs into a Python virtualenv on the host. No Docker required. The Hub serves a version-pinned wheel, so the Hub controls which agent version runs.

Needs: python3 3.11+, outbound HTTPS.

Alternative

Docker

Runs the agent as a container from GHCR. Useful where a container runtime is already the norm.

Needs: Docker + Compose, and docker login ghcr.io — the image is private.

Admin workflow

The Hub stores the organization agent key and generates an installer with the key already embedded. You never copy a key by hand, and the database host never needs inbound access from the Hub.

  1. Step 1

    Sign in as an admin

    Open the Hub and sign in with an owner or admin account.

    https://dba.smart-apps.in

  2. Step 2

    Open Remote Agents and confirm an active key

    Go to Settings → Remote Agents. Confirm your organization has an active agent key. If none exists, create one here — the installer cannot be generated without it.

    /settings/agent-keys

  3. Step 3

    Download the standalone installer

    Choose Standalone. The downloaded install-dba-agent.sh embeds your organization key and pins the current agent wheel served by this Hub.

    If the browser opens a save dialog, choose a known folder such as Downloads and complete Save. Confirm the file exists before leaving this page; the success notification confirms generation, not that an operating-system file dialog was completed.

    Treat the installer as a secret. It contains your organization key. Do not commit it, paste it into tickets, or host it anywhere fetchable.

  4. Step 4

    Run it near the database

    Run on a Linux host that can reach both the Hub over HTTPS and the database over its native port. Not on the Hub itself.

  5. Step 5

    Add instances from the Hub

    Add database instances in the Hub and select the running agent. No YAML edit and no agent restart is required.

    /instances

  6. Step 6

    Verify readiness

    Confirm the agent is online, each instance has a runtime readiness status, and metrics begin to arrive.

    /agents

Prerequisites

Host runtime

  • Linux host with python3 3.11+ (standalone), or Docker + Compose
  • Outbound HTTPS to api.dba.smart-apps.in and agent.dba.smart-apps.in — no inbound ports
  • Network reach to the database over its native port
  • Disk for backups and logs under the agent directory

Operational access

  • Admin access to the Hub (to generate the installer)
  • Database monitoring credentials for each instance
  • Optional sudo for systemd service install
  • Proxy or private CA details, if your network requires them

Native database tools

The agent shells out to the vendor's own tools for backups and maintenance. Install the client tools for whichever engines this host will manage. The self-check reports missing tools as warnings rather than failing when you pass --warn-missing-tools, so you can install the agent first and add tools as capabilities are needed.

MongoDB monitoring uses the Python driver included with the agent. Install MongoDB Database Tools separately from the vendor only when backup/restore commands such as mongodump are required.

Ubuntu / Debian

Base runtime

sudo apt-get update
sudo apt-get install -y \
  python3 python3-venv python3-pip \
  ca-certificates curl unzip

Database tools

sudo apt-get install -y \
  default-mysql-client postgresql-client

RHEL / Amazon Linux

Base runtime

sudo dnf install -y \
  python3 python3-pip \
  ca-certificates curl unzip

Database tools

sudo dnf install -y mysql postgresql

macOS (dev only)

Base runtime

brew install python@3.11

Database tools

brew install mysql-client libpq

systemd is unavailable on macOS; the agent runs in the foreground.

Install the standalone agent default

1. Copy and run the downloaded installer

The installer already contains your organization key and the Hub URL. Nothing to edit. 

scp install-dba-agent.sh user@db-host:/tmp/
ssh user@db-host
chmod +x /tmp/install-dba-agent.sh
/tmp/install-dba-agent.sh

It creates a virtualenv, installs the wheel this Hub serves, writes agent.yaml, registers with the Hub, and runs a preflight self-check. The wheel is version-pinned by the Hub: 

https://agent.dba.smart-apps.in/artifacts/agent_generic-0.1.27-py3-none-any.whl

Default install directory is $HOME/.dba-agent. Override with AGENT_DIR=/opt/dba-agent.

Dependencies still come from your Python index

The Hub serves the agent wheel only, not a full dependency bundle. The host needs access to PyPI or a configured internal index, unless the dependencies are already cached. On an air-gapped host, point AGENT_PACKAGE at a local wheelhouse.

2. Install as a background service

Without this the agent stops when your shell exits. 

/tmp/install-dba-agent.sh --systemd
systemctl status dba-agent --no-pager

3. Re-run the self-check manually

Safe to run at any time; it does not restart the agent. 

cd ~/.dba-agent
./.venv/bin/dba-agent self-check \
  --config ./agent.yaml --warn-missing-tools

On a Hub-managed install this release keeps database assignments in memory, not in agent.yaml. The local self-check therefore validates the installation and Hub reachability; use the Hub's runtime readiness and advancing metric timestamps to verify assigned databases.

Install with Docker

Download the installer in docker mode from Settings → Remote Agents.

Authenticate to GHCR first

The agent image is private. Without this the pull fails with denied or manifest unknown. 

echo '<read:packages token>' | docker login ghcr.io -u <github-user> --password-stdin
chmod +x install-dba-agent.sh
./install-dba-agent.sh

It writes a compose file, pulls ghcr.io/dbapilot-ai/dba-agent-generic:latest, runs a self-check, then starts the agent. Note docker mode tracks :latest rather than a Hub-pinned version — set AGENT_IMAGE to an explicit tag if you need the version fixed.

Upgrade the agent in place

Recommended: one-command upgrade

Run on the agent host. The script contains no credentials — it reads the identity already in your agent.yaml, which is why it can be fetched directly. 

curl -fsSL https://agent.dba.smart-apps.in/artifacts/docs/upgrade-dba-agent.sh \
  -o upgrade-dba-agent.sh
sudo bash upgrade-dba-agent.sh --version 0.1.27

What the script handles

  • Detects standalone, systemd and Docker Compose installs automatically
  • Saves the current wheel first, so a rollback target exists
  • Verifies the target wheel against its published SHA-256 before installing
  • Backs up agent.yaml and confirms it is unchanged afterwards
  • Adopts an unsupervised install into a dba-agent.service so future upgrades are predictable
  • Leaves agent identity, key and instance assignments intact

Only if auto-detection finds multiple installs

Point it at the right directory explicitly. 

sudo bash upgrade-dba-agent.sh \
  --agent-dir /home/ubuntu/.dba-agent \
  --version 0.1.27

Other flags: --mode auto|standalone|docker, --hub-origin URL, --strict, --allow-no-rollback.

Self-check behavior

A package, version, or service-start failure triggers automatic rollback. A database network or privilege failure is printed as a warning and the agent stays upgraded and running — upgrading the agent cannot repair VPC routes or database security groups. Add --strict if every self-check failure must roll back.

Upgrade completion gate

The upgrade is complete when the Hub reports the agent at version 0.1.27, Online, and connected. Database readiness is a separate gate: instances must report OK and metric timestamps must advance after the collector interval. A DB Unreachable state needs network or database remediation, not another agent upgrade.

Verify the wheel independently

curl -fsSLO https://agent.dba.smart-apps.in/artifacts/agent_generic-0.1.27-py3-none-any.whl
curl -fsSLO https://agent.dba.smart-apps.in/artifacts/agent_generic-0.1.27-py3-none-any.whl.sha256
sha256sum -c agent_generic-0.1.27-py3-none-any.whl.sha256

Docker

cd /opt/dba-agent
docker compose -f docker-compose.client.yml pull agent
docker compose -f docker-compose.client.yml run --rm agent self-check --warn-missing-tools
docker compose -f docker-compose.client.yml up -d

Attach database instances from the Hub

Instances are added in the Hub and assigned to a running agent. Nothing is edited on the agent host and no restart is needed — the agent picks up its assignment on the next poll.

  1. Go to /instances and add the database
  2. Set host, port, username, password and Default Database
  3. For MongoDB, set Authentication Database (normally admin for a root user)
  4. Select the agent that should manage it
  5. Run Test Database Connection

Default Database must be an application schema

Not mysql, information_schema, performance_schema or sys. Pointing at a system schema is the most common cause of 1044 Access denied on the connection test.

MongoDB uses two database settings

Keep Default Database on the application database whose metrics you need. Set Authentication Database to the database where the user was created. Using the application database as the auth source for an admin root user causes Authentication failed (code 18).

Database connection checks

Run these from the agent host to prove network reachability before adding the instance. They isolate a network problem from a credential or Hub problem. 

mysql -h <db-host> -P 3306 -u <user> -p -e "select 1;"

PGPASSWORD='<password>' psql -h <db-host> -p 5432 -U <user> -d <database> -c 'select 1;'

mongosh --host <db-host> --port 27017 --username <user> \
  --authenticationDatabase admin --password \
  --eval 'db.runCommand({ping: 1})'

Verify the rollout

Hub health

curl -fsS https://api.dba.smart-apps.in/health

Expect {"status":"ok"}.

Agent wheel

curl -I https://agent.dba.smart-apps.in/artifacts/\
agent_generic-0.1.27-py3-none-any.whl

Expect 200.

Agent status

/agents — the agent should be online with a recent heartbeat and the expected version.

Instance readiness

Each assigned instance should report online / OK, and metric timestamps should advance after one collector interval.

Troubleshooting

pip cannot find the agent package

If the installer reports it cannot install agent-generic (a bare name rather than a URL), the Hub is not pinning a version and fell back to a package that exists on no public index. Ask an admin to publish and pin a wheel. As a stopgap: 

AGENT_PACKAGE=https://agent.dba.smart-apps.in/artifacts/agent_generic-0.1.27-py3-none-any.whl \
  ./install-dba-agent.sh
TLS or certificate errors talking to the Hub 
curl -fsS https://api.dba.smart-apps.in/health
openssl s_client -connect api.dba.smart-apps.in:443 -servername dba.smart-apps.in </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -dates

A name mismatch usually means the host is reaching something other than the Hub; an expiry or trust error usually means a stale CA bundle or an intercepting proxy.

Docker pull denied

The agent image is private. Run docker login ghcr.io with a token that has read:packages, then retry.

Database connection test fails

Treat a database-native error as an agent-side result, not a browser problem. 1044 Access denied ... to database 'mysql' means the agent reached MySQL but Default Database is a system schema — set it to the application schema. If the target schema is already correct, fix the grants for the monitoring account.

Agent installed but shows offline

The agent polls outbound, so an offline agent is nearly always a process or egress problem rather than anything on the Hub. 

systemctl status dba-agent --no-pager
journalctl -u dba-agent -n 100 --no-pager
Upgrade rolled itself back

That is the script working as designed — a package, version or service-start failure restores the previous wheel. Read the output for the failing step. If it could not download the previous wheel it stops rather than proceeding without a rollback path; --allow-no-rollback overrides that, but only after you have accepted the risk.

Support bundle

Collect this when raising an issue. Redact credentials from agent.yaml before sharing — it contains your organization key and database passwords. 

cd ~/.dba-agent
./.venv/bin/dba-agent self-check \
  --config ./agent.yaml --warn-missing-tools
systemctl status dba-agent --no-pager
journalctl -u dba-agent -n 200 --no-pager
curl -fsS https://api.dba.smart-apps.in/health
python3 --version
uname -a