# Self-managed server

For PostgreSQL installed directly on a server, outside a container or a managed service, run the
collector as a container alongside it and add `node_exporter` on each database host.

Before you start, create the database login and write `collector.toml` as described in
[Choose your setup](/docs/connect/).  A complete file is in
[Self-managed PostgreSQL](#self-managed-postgresql).

## Running the collector

Run it on a Docker host, with the config file in the current directory.  `:latest` is convenient
while you try it out.  For anything you intend to keep running, pin a release tag or a digest, so a
restart cannot silently change the running version:

```bash
# Pin a release tag instead of :latest in production.
docker run --rm \
  -v "$PWD/collector.toml:/etc/dbg-collector/collector.toml:ro" \
  -e DBG_SERVER_SECRET="<secret from the app>" \
  -e DB_PASSWORD="<your database password>" \
  dbgorillapublic.azurecr.io/dbg-collector:latest \
  --config-file /etc/dbg-collector/collector.toml
```

The collector is an ordinary container, so it also runs under Docker Compose or in Kubernetes.  For
Kubernetes there is an official Helm chart at
`oci://dbgorillapublic.azurecr.io/charts/dbg-collector`.  It takes the same `collector.toml` and
requires Kubernetes 1.25 or newer:

```bash
helm install dbg-collector oci://dbgorillapublic.azurecr.io/charts/dbg-collector \
  --namespace dbg-collector --create-namespace \
  --set-file config.inline=./collector.toml \
  --set secrets.serverSecret="<secret from the app>" \
  --set-string secrets.databasePasswords.DB_PASSWORD="<your database password>"
```

The chart creates only core Kubernetes objects, with no operator or custom resources.  Its pod
meets the `restricted` Pod Security Standard, so it installs into a namespace that enforces it.

See [Query plans are on in the sample](/docs/reference/collector-commands/#query-plans-are-on-in-the-sample) in Collector commands.

## node_exporter

`node_exporter` is an open-source Prometheus exporter that provides host metrics to the collector.
The collector discovers exporters automatically on the default port 9100 on your database hosts.
Where port 9100 is not exposed, set `mode = "disabled"` under `[component.provider.node_exporter]`
so the probe does not stall discovery.

The Prometheus project maintains it, and it is free to download from
[github.com/prometheus/node_exporter](https://github.com/prometheus/node_exporter).  It is packaged
in EPEL for RHEL-based distributions, and runs under Docker with:

```bash
docker run -d \
  --net="host" \
  --pid="host" \
  -v "/:/host:ro,rslave" \
  quay.io/prometheus/node-exporter:latest \
  --path.rootfs=/host
```

With metrics flowing, DBGorilla is usable from the dashboard.  To bring your team in, see
[Organization Management](/docs/administer/members-and-roles/).

## Self-managed PostgreSQL

This config is for PostgreSQL you run yourself, on a VM, a bare-metal host or in a container, with
the collector running as a Docker container that can reach it.

```toml
[dbgorilla]
agent_id  = "<agent id from the app>"
tenant_id = "<tenant id from the app>"
secret    = "${DBG_SERVER_SECRET}"

[[component]]
name   = "orders"
engine = "postgres"

[component.provider]
type = "self_hosted"

[component.auth]
method   = "password"
user     = "dbg_readonly"
password = "${ORDERS_DB_PASSWORD}"

[component.connect]
host      = "db.internal.example.com"
port      = 5432
databases = ["orders"]
ssl_mode  = "verify-full"

[topology]
interval = "60s"

[commands]
enabled = true
allowed = ["explain", "collect_statistics"]   # see https://www.dbgorilla.com/docs/reference/collector-commands/#database-commands
```

Run it with the secrets in a separate file, mode 0600 and out of version control:

```ini
# secrets.env
DBG_SERVER_SECRET=your-client-secret
ORDERS_DB_PASSWORD=your-database-password
```

```sh
docker run --rm \
  -v "$PWD/collector.toml:/etc/dbg-collector/collector.toml:ro" \
  --env-file secrets.env \
  dbgorillapublic.azurecr.io/dbg-collector:latest \
  --config-file /etc/dbg-collector/collector.toml
```

Pin a release tag in place of `latest` for anything you keep running.  For host metrics, run
`node_exporter` on the database host; see [node_exporter](#node_exporter).

For PostgreSQL on your own laptop, the CLI writes this file:
`dbgorilla collector install --target docker`.  See
[Your machine (Docker)](/docs/connect/docker/).

## Self-managed MySQL

This config is for MySQL 8.0 or later that you run yourself, with the collector in a Docker
container.

```toml
[dbgorilla]
agent_id  = "<agent id from the app>"
tenant_id = "<tenant id from the app>"
secret    = "${DBG_SERVER_SECRET}"

[[component]]
name   = "staging-mysql"
engine = "mysql"

[component.provider]
type = "self_hosted"

[component.auth]
method   = "password"
user     = "dbg_monitor"
password = "${MYSQL_PASSWORD}"

[component.connect]
host      = "mysql.internal"
port      = 3306
databases = ["app"]
ssl_mode  = "verify_identity"   # disabled | required | verify_ca | verify_identity (default)

[topology]
interval = "60s"

[commands]
enabled = true
allowed = ["explain", "collect_statistics"]   # see https://www.dbgorilla.com/docs/reference/collector-commands/#database-commands
```

`ssl_mode` uses MySQL's spellings, with underscores.  What a PostgreSQL value does is on [Collector configuration](/docs/reference/collector-configuration/#mysql).

Run it with the same `docker run` as [Self-managed PostgreSQL](#self-managed-postgresql), with
`secrets.env` holding `DBG_SERVER_SECRET` and `MYSQL_PASSWORD`.  The `performance_schema`
consumers MySQL needs turned on are listed on [MySQL](/docs/connect/prepare-mysql/).