Skip to content

Docker

How to run PMM Server with Docker based on our Docker image.

The tags used here are for the current release. Other tags are available.

Before you start

  • Install Docker 1.12.6 or higher.

Run

Summary

  • Pull the Docker image.
  • Copy it to create a persistent data container.
  • Run the image.
  • Open the PMM UI in a browser.

  1. Pull the image.

    docker pull percona/pmm-server:2
    
  2. Create a persistent data container.

    docker create --volume /srv \
    --name pmm-data \
    percona/pmm-server:2 /bin/true
    

    Important

    PMM Server expects the data volume to be /srv. Using any other value will result in data loss when upgrading.

    To check server and data container mount points:

    docker inspect pmm-data | grep Destination && \
    docker inspect pmm-server | grep Destination
    
  3. Run the image.

    docker run --detach --restart always \
    --publish 443:443 \
    --volumes-from pmm-data \
    --name pmm-server \
    percona/pmm-server:2
    
  4. Change the password for the default admin user.

    • For PMM versions 2.27.0 and later:
    docker exec -t pmm-server change-admin-password <new_password>
    
    • For PMM versions prior to 2.27.0:

      docker exec -t pmm-server bash -c 'grafana-cli --homepath /usr/share/grafana --configOverrides cfg:default.paths.data=/srv/grafana admin reset-admin-password newpass'
      
  5. Visit https://localhost:443 to see the PMM user interface in a web browser. (If you are accessing the docker host remotely, replace localhost with the IP or server name of the host.)

Backup

Summary

  • Stop and rename the pmm-server container.
  • Take a local copy of the pmm-data container’s /srv directory.

Important

Grafana plugins have been moved to the data volume /srv since the 2.23.0 version. So if you are upgrading PMM from any version before 2.23.0 and have installed additional plugins then plugins should be installed again after the upgrade.

To check used grafana plugins:

docker exec -it pmm-server ls /var/lib/grafana/plugins
  1. Stop the container.

    docker stop pmm-server
    
  2. Move the image.

    docker rename pmm-server pmm-server-backup
    
  3. Create a subdirectory (e.g., pmm-data-backup) and move to it.

    mkdir pmm-data-backup && cd pmm-data-backup
    
  4. Backup the data.

    docker cp pmm-data:/srv .
    

Upgrade

Summary

  • Stop the running container.
  • Backup (rename) the container and copy data.
  • Pull the latest Docker image.
  • Run it.

Important

Downgrades are not possible. To go back to using a previous version you must have created a backup of it before upgrading.

Tip

To see what release you are running, use the PMM Upgrade panel on the Home Dashboard, or run:

docker exec -it pmm-server \
curl -ku admin:admin https://localhost/v1/version

(If you are accessing the docker host remotely, replace localhost with the IP or server name of the host.)

  1. Stop the container.

    docker stop pmm-server
    
  2. Perform a backup.

  3. Pull the latest image.

    docker pull percona/pmm-server:2
    
  4. Run it.

    docker run \
    --detach \
    --restart always \
    --publish 443:443 \
    --volumes-from pmm-data \
    --name pmm-server \
    percona/pmm-server:2
    

Restore

Summary

  • Stop and remove the container.
  • Restore (rename) the backup container.
  • Restore saved data to the data container.
  • Restore permissions to the data.

Important

You must have a backup to restore from.

  1. Stop the container.

    docker stop pmm-server
    
  2. Remove it.

    docker rm pmm-server
    
  3. Revert to the saved image.

    docker rename pmm-server-backup pmm-server
    
  4. Change directory to the backup directory (e.g. pmm-data-backup).

  5. Remove Victoria Metrics data folder.

    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 rm -r /srv/victoriametrics/data
    
  6. Copy the data.

    docker cp srv pmm-data:/
    
  7. Restore permissions.

    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R root:root /srv && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R pmm:pmm /srv/alertmanager && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R root:pmm /srv/clickhouse && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R grafana:grafana /srv/grafana && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R pmm:pmm /srv/logs && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R postgres:postgres /srv/postgres && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R pmm:pmm /srv/prometheus && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R pmm:pmm /srv/victoriametrics && \
    docker run --rm --volumes-from pmm-data -it percona/pmm-server:2 chown -R postgres:postgres /srv/logs/postgresql.log
    
  8. Start the image.

    docker start pmm-server
    

Remove

Summary

  • Stop the container.
  • Remove (delete) both the server and data containers.
  • Remove (delete) both images.

Caution

These steps delete the PMM Server Docker image and any accumulated PMM metrics data.

  1. Stop pmm-server container.

    docker stop pmm-server
    
  2. Remove containers.

    docker rm pmm-server pmm-data
    
  3. Remove the image.

    docker rmi $(docker images | grep "percona/pmm-server" | awk {'print $3'})
    

Environment variables

Use the following Docker container environment variables (with -e var=value) to set PMM Server parameters.

Variable Description
DISABLE_UPDATES Disables a periodic check for new PMM versions as well as ability to apply upgrades using the UI
DISABLE_TELEMETRY Disable built-in telemetry and disable STT if telemetry is disabled.
METRICS_RESOLUTION High metrics resolution in seconds.
METRICS_RESOLUTION_HR High metrics resolution (same as above).
METRICS_RESOLUTION_MR Medium metrics resolution in seconds.
METRICS_RESOLUTION_LR Low metrics resolution in seconds.
DATA_RETENTION How many days to keep time-series data in ClickHouse.
ENABLE_VM_CACHE Enable cache in VM.
ENABLE_ALERTING Enable integrated alerting.
ENABLE_AZUREDISCOVER Enable support for discovery of Azure databases.
ENABLE_BACKUP_MANAGEMENT Enable integrated backup tools.
PERCONA_TEST_SAAS_HOST SaaS server hostname.
PERCONA_TEST_DBAAS Enable testing DBaaS features. (Will be deprecated in future versions.)
ENABLE_DBAAS Enable DBaaS features.
PMM_DEBUG Enables a more verbose log level.
PMM_TRACE Enables a more verbose log level including trace-back information.
PMM_PUBLIC_ADDRESS External IP address or the DNS name on which PMM server is running.

Ignored variables

These variables will be ignored by pmm-managed when starting the server. If any other variable is found, it will be considered invalid and the server won’t start.

Variable Description
_, HOME, HOSTNAME, LANG, PATH, PWD, SHLVL, TERM Default environment variables.
GF_* Grafana’s environment variables.
SUPERVISOR_ supervisord environment variables.
PERCONA_TEST_ Unknown variable but won’t prevent the server starting.
PERCONA_TEST_DBAAS Deprecated. Use ENABLE_DBAAS.

Tips

  • To Disable the Home Dashboard PMM Upgrade panel you can either add -e DISABLE_UPDATES=true to the docker run command (for the life of the containter) or navigate to PMM → PMM Settings → Advanced Settings and disable “Check for Updates” (can be turned back on by any admin in the UI).

  • Eliminate browser certificate warnings by configuring a trusted certificate.

  • You can optionally enable an (insecure) HTTP connection by adding --publish 80:80 to the docker run command. However, running PMM insecure is not recommended. You should also note that PMM Client requires TLS to communicate with the server, only working on a secure port.

Isolated hosts

If the host where you will run PMM Server has no internet connection, you can download the Docker image on a separate (internet-connected) host and securely copy it.

  1. On an internet-connected host, download the Docker image and its checksum file.

    wget https://downloads.percona.com/downloads/pmm2/2.28.0/docker/pmm-server-2.28.0.docker
    wget https://downloads.percona.com/downloads/pmm2/2.28.0/docker/pmm-server-2.28.0.sha256sum
    
  2. Copy both files to where you will run PMM Server.

  3. Open a terminal on the PMM Server host.

  4. (Optional) Check the Docker image file integrity.

    shasum -ca 256 pmm-server-2.28.0.sha256sum
    
  5. Load the image.

    docker load -i pmm-server-2.28.0.docker
    
  6. Create the pmm-data persistent data container.

    docker create --volume /srv \
    --name pmm-data percona/pmm-server:2.28.0 /bin/true
    
  7. Run the container.

    docker run \
    --detach \
    --restart always \
    --publish 443:443 \
    --volumes-from pmm-data \
    --name pmm-server \
    percona/pmm-server:2.28.0
    

Last update: 2022-05-23