Runbook: Prepare and Start

No --branch installs main — the latest production release. That is the installer’s own default (misc/hub/install.sh, misc/bootstrap.sh), not just this page’s convention: every command below is safe to copy as-is. Pin to a specific supported line instead with --branch release/<major>.<minor>.x (e.g. release/1.7.x) — see docs/RELEASE-WORKFLOW.md for which lines are currently maintained. A bare --branch main also works and says the same thing out loud, if you prefer to be explicit.

One-time on each stack host: two of the images are ours and live in a private project on the hub, so log in before installing. Everything else is public.

docker login hub.friendly-tech.com -u ast   # read-only account, ask for the password

Skip it and the install stops before starting anything, telling you to run exactly this. An air-gapped install needs no login at all — the images come in the bundle.

Note: Bootstrap does not support Windows. For Windows servers, install Windows Exporter manually (see section 7).

No registry login is needed here. Everything, including the two images we build ourselves, comes from the bundle. If Docker asks for authorization during an offline install, the images are not on the host — see Troubleshooting → Docker asks for authorization, which lists the three reasons in order of likelihood.

Prerequisite: Docker and Docker Compose must already be installed on the air-gapped server — /opt/grafana/misc/install-docker.sh needs internet access (OS package repositories). Use your OS vendor’s offline packages if Docker is missing.

Monitoring stack node (Prometheus/Grafana) offline: once the image bundle is loaded (docker load), install the stack — no manual section-8 steps needed. Pick the mode:

# Interactive (recommended for a manual install) — runs the configurator and
# PROMPTS for GRAFANA_DOMAIN, admin/prometheus passwords, SMTP, etc.:
sudo bash /opt/grafana/misc/bootstrap.sh stack

# Non-interactive (for curl|bash / headless) — asks NOTHING. It auto-derives
# GRAFANA_DOMAIN from the server IP (self-signed cert) and generates random
# admin/prometheus passwords, printed in the final summary:
sudo bash /opt/grafana/misc/bootstrap.sh stack -y

Both use localhost for Prometheus. -y never ships the .env CHANGE_ME placeholders — the must-have values (IP/domain, passwords, service token) are filled automatically; only optional bits (SMTP, Business-dashboard DB) stay unset.

With Docker already present and the repo in place, bootstrap skips the internet-only steps (Docker install, git clone, Let’s Encrypt) and does the rest offline: creates .env from .env.example, generates a self-signed cert + htpasswd + the alertmanager placeholder, starts all containers from the pre-loaded images, deploys the base exporters, and generates targets. It also auto-stages the bundled Grafana plugins: it looks for a docker-images-bundle-grafana-plugins/ folder — with the plugin .zip files directly inside it, no subfolder — in /opt, /tmp and /opt/grafana, checked in that order, and copies its zips into grafana/data/offline-plugins/; the Grafana entrypoint then installs them from disk and skips grafana.com. Auto-staging only runs when offline-plugins/ is empty — if it already holds any .zip, bootstrap leaves it alone.

offline-plugins/ vs plugins/: offline-plugins/ is the input — the zips bootstrap (or you) stage — while plugins/ is the output the entrypoint unzips them into; copying zips into plugins/ does nothing. If you keep the plugin zips outside the three auto-staged locations, stage them manually first:

sudo mkdir -p /opt/grafana/prometheus-grafana-stack/grafana/data/offline-plugins
sudo cp /tmp/docker-images-bundle-grafana-plugins/*.zip \
     /opt/grafana/prometheus-grafana-stack/grafana/data/offline-plugins/
sudo chown -R 472:472 /opt/grafana/prometheus-grafana-stack/grafana/data

The chown matters — Grafana runs as uid 472 and must be able to write under grafana/data.

For Oracle deployments, also extract the Oracle datasource plugin (normally downloaded by bootstrap from GitHub):

sudo mkdir -p /opt/grafana/prometheus-grafana-stack/grafana/data/plugins/albertowd-oraclegrafana-datasource
sudo tar -xzf /tmp/docker-images-bundle-grafana-plugins/albertowd-oraclegrafana-datasource.tar.gz \
     -C /opt/grafana/prometheus-grafana-stack/grafana/data/plugins/albertowd-oraclegrafana-datasource