Skip to content
Klutch.sh Docs

Deploying Grafana

Introduction

Grafana is an open-source platform for monitoring and observability that allows you to query, visualize, alert on, and understand your metrics regardless of where they are stored. With powerful and elegant dashboards, Grafana enables you to create, explore, and share data through beautiful, flexible visualizations.

Deploying Grafana on Klutch.sh provides you with a scalable, reliable infrastructure for your monitoring and analytics needs. This guide will walk you through deploying Grafana using a Dockerfile, configuring persistent storage for your dashboards and data sources, and implementing best practices for production deployments.

Whether you’re monitoring application performance, infrastructure metrics, or business analytics, Grafana on Klutch.sh offers the flexibility and power you need with automated deployments and seamless scaling.

Prerequisites

Before you begin deploying Grafana on Klutch.sh, ensure you have the following:

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your Grafana deployment configuration
  • Basic knowledge of Docker and monitoring concepts
  • Understanding of Grafana data sources (optional, but helpful)

Step 1: Prepare Your Grafana Repository

  1. Create a new GitHub repository or use an existing one for your Grafana deployment.
  2. Clone the repository to your local machine to add the necessary configuration files.
  3. Plan your deployment structure, including any custom dashboards, plugins, or data source configurations you want to include.

For repository setup and GitHub integration, refer to the Klutch.sh Quick Start Guide.

Important Note: Store sensitive data such as API keys, database credentials, and other secrets as environment variables in Klutch.sh rather than in your Git repository. Large assets like provisioning files, dashboard JSONs, or plugin files should be stored using persistent volumes or fetched from object storage at runtime.

Step 2: Create a Dockerfile for Grafana

Klutch.sh automatically detects a Dockerfile if present in the root directory of your repository. Create a Dockerfile in the root of your repository with the following content:

FROM grafana/grafana:latest


# Set the working directory
WORKDIR /usr/share/grafana


# Optional: Copy custom configuration files
# COPY ./grafana.ini /etc/grafana/grafana.ini


# Optional: Copy custom provisioning files for datasources and dashboards
# COPY ./provisioning /etc/grafana/provisioning


# Optional: Install custom plugins
# RUN grafana-cli plugins install <plugin-name>


# Expose Grafana's default port
EXPOSE 3000


# The official Grafana image already has a default entrypoint
# No need to specify CMD or ENTRYPOINT unless customizing

Dockerfile Explanation

  • Base Image: We use the official grafana/grafana:latest image, which includes all necessary dependencies and configurations.
  • Custom Configuration: Optionally copy a custom grafana.ini file to configure Grafana settings like authentication, server settings, and database connections.
  • Provisioning: Optionally copy provisioning files to automatically configure data sources, dashboards, and notification channels on startup.
  • Plugins: Install any required Grafana plugins using grafana-cli during the build process.
  • Port Exposure: Grafana runs on port 3000 by default, which we expose for HTTP traffic.

Example Dockerfile with Custom Configuration

FROM grafana/grafana:10.2.3


# Install specific plugins
RUN grafana-cli plugins install grafana-clock-panel && \
    grafana-cli plugins install grafana-piechart-panel && \
    grafana-cli plugins install grafana-worldmap-panel


# Copy custom provisioning configurations
COPY ./provisioning /etc/grafana/provisioning


# Expose port 3000
EXPOSE 3000

Step 3: Configure Grafana Settings (Optional)

You can customize Grafana’s behavior by creating a custom grafana.ini file. Here’s an example configuration:

[server]
protocol = http
http_port = 3000
domain = example-app.klutch.sh
root_url = https://example-app.klutch.sh


[database]
type = sqlite3
path = /var/lib/grafana/grafana.db


[security]
admin_user = admin
# admin_password should be set via environment variable


[auth.anonymous]
enabled = false


[users]
allow_sign_up = false


[log]
mode = console
level = info

Important: Store sensitive values like admin_password as environment variables in Klutch.sh rather than in configuration files.

Step 4: Set Up Provisioning (Optional)

Grafana supports provisioning data sources and dashboards via configuration files. Create a provisioning directory structure in your repository:

provisioning/
├── datasources/
│   └── datasource.yml
└── dashboards/
    ├── dashboard.yml
    └── my-dashboard.json

Example Data Source Configuration

Create provisioning/datasources/datasource.yml:

apiVersion: 1


datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus-server:9090
    isDefault: true
    editable: false

Example Dashboard Provisioning

Create provisioning/dashboards/dashboard.yml:

apiVersion: 1


providers:
  - name: 'Default'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    updateIntervalSeconds: 10
    allowUiUpdates: true
    options:
      path: /etc/grafana/provisioning/dashboards

Then place your dashboard JSON files in the provisioning/dashboards/ directory.

Step 5: Push Your Repository to GitHub

Commit and push your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add .
git commit -m "Add Grafana Dockerfile and configuration"
git push origin main

Step 6: Deploy Grafana on Klutch.sh

  1. Log in to your Klutch.sh account and navigate to the dashboard.

  2. Create a new project or select an existing project where you want to deploy Grafana.

  3. Click on Create New App and provide the following information:

    • App Name: Give your Grafana deployment a descriptive name (e.g., “grafana-monitoring”)
    • GitHub Repository: Select the repository containing your Grafana Dockerfile
    • Branch: Choose the branch to deploy (typically main or master)

  4. Configure the deployment settings:

    • Traffic Type: Select HTTP (Grafana uses HTTP/HTTPS for its web interface)
    • Internal Port: Set to 3000 (Grafana’s default port)
    • Region: Choose your preferred deployment region
    • Compute Resources: Select appropriate CPU and memory based on your expected load (recommended: at least 1 CPU and 2GB RAM for production use)
    • Instances: Start with 1 instance; you can scale later based on traffic

  5. Click Create to start the deployment process.

Klutch.sh will automatically detect your Dockerfile, build the image, and deploy your Grafana instance. The build process typically takes 3-5 minutes depending on the complexity of your configuration and any plugins being installed.

Step 7: Configure Environment Variables

To securely configure Grafana, set up environment variables in the Klutch.sh dashboard:

  1. Navigate to your Grafana app in the Klutch.sh dashboard.

  2. Go to the Environment Variables section.

  3. Add the following environment variables:

Essential Variables:

Terminal window
GF_SECURITY_ADMIN_USER=admin
GF_SECURITY_ADMIN_PASSWORD=your-secure-password-here
GF_SERVER_ROOT_URL=https://your-app.klutch.sh
GF_SERVER_DOMAIN=your-app.klutch.sh

Optional Security Variables:

Terminal window
GF_SECURITY_SECRET_KEY=your-random-secret-key
GF_AUTH_ANONYMOUS_ENABLED=false
GF_USERS_ALLOW_SIGN_UP=false
GF_USERS_DEFAULT_THEME=dark

Database Configuration (if using external database):

Terminal window
GF_DATABASE_TYPE=postgres
GF_DATABASE_HOST=your-database-host:5432
GF_DATABASE_NAME=grafana
GF_DATABASE_USER=grafana_user
GF_DATABASE_PASSWORD=your-database-password
GF_DATABASE_SSL_MODE=require

SMTP Configuration (for email alerts):

Terminal window
GF_SMTP_ENABLED=true
GF_SMTP_HOST=smtp.gmail.com:587
GF_SMTP_USER=your-email@gmail.com
GF_SMTP_PASSWORD=your-email-password
GF_SMTP_FROM_ADDRESS=your-email@gmail.com
GF_SMTP_FROM_NAME=Grafana

Important: Always mark sensitive variables as secrets in the Klutch.sh UI to prevent them from appearing in logs or being exposed.

Step 8: Set Up Persistent Storage

Grafana requires persistent storage to maintain dashboards, user settings, data source configurations, and plugin data across deployments and restarts.

  1. In your Grafana app settings on Klutch.sh, navigate to the Volumes section.

  2. Click Add Volume to create a new persistent volume.

  3. Configure the volume:

    • Mount Path: /var/lib/grafana (Grafana’s data directory)
    • Size: Recommended minimum of 10GB; increase based on the number of dashboards and plugins

  4. Click Save to attach the volume to your Grafana deployment.

The persistent volume will store:

  • SQLite database (if using the default database)
  • User sessions
  • Dashboard definitions
  • Plugin data
  • Grafana configuration state

Note: If you’re using an external database (PostgreSQL, MySQL), you primarily need the volume for plugin data and temporary files, so a smaller volume size may suffice.

Additional Volumes for Custom Needs

If you have custom provisioning files or plugins that you want to persist separately:

/etc/grafana/provisioning  <- provisioning-data (5GB)
/var/lib/grafana/plugins   <- custom-plugins (5GB)

Step 9: Configure Data Sources

After deployment, configure your data sources to start visualizing data:

  1. Access your Grafana instance at https://your-app.klutch.sh.

  2. Log in with the admin credentials you set in the environment variables.

  3. Navigate to Configuration → Data Sources.

  4. Click Add data source and select your data source type (Prometheus, InfluxDB, MySQL, PostgreSQL, etc.).

  5. Configure the connection settings:

    • URL: The endpoint of your data source
    • Authentication: Credentials or API keys as needed
    • Additional Settings: Any specific configuration required by your data source

  6. Click Save & Test to verify the connection.

Tip: For data sources within the same Klutch.sh project, you can use internal networking to connect services securely without exposing them to the public internet.

Step 10: Import or Create Dashboards

Grafana’s power lies in its dashboards. You can either import pre-built dashboards or create custom ones:

Importing Dashboards

  1. Navigate to Create → Import in the Grafana sidebar.

  2. Enter a dashboard ID from Grafana’s dashboard library or upload a JSON file.

  3. Select the data source to use for the dashboard.

  4. Click Import to add the dashboard to your Grafana instance.

Creating Custom Dashboards

  1. Click Create → Dashboard.

  2. Click Add a new panel.

  3. Configure your panel:

    • Select the data source
    • Write your query
    • Choose visualization type
    • Customize display options

  4. Click Apply to add the panel to your dashboard.

  5. Repeat to add more panels, then click Save dashboard and provide a name.

Step 11: Configure Alerting (Optional)

Grafana supports alerting to notify you when metrics exceed thresholds:

  1. Navigate to Alerting → Notification channels.

  2. Click Add channel and select your notification method (email, Slack, PagerDuty, webhook, etc.).

  3. Configure the notification channel settings and test it.

  4. In your dashboard panels, click the panel title → Edit.

  5. Go to the Alert tab and click Create Alert.

  6. Define alert conditions and select notification channels.

  7. Save the panel and dashboard.

Environment Variables for Nixpacks Customization

Since Klutch.sh uses Nixpacks for builds, you can customize the build and runtime behavior using environment variables. However, when using a Dockerfile, Nixpacks respects the Dockerfile instructions directly.

If you need to customize the start command or build command without modifying the Dockerfile:

Build-time Variables:

Terminal window
NIXPACKS_BUILD_CMD=grafana-cli plugins install <plugin-name>

Runtime Variables:

Terminal window
NIXPACKS_START_CMD=/run.sh

For most Grafana deployments, the official Docker image’s default entrypoint and command are sufficient and don’t require customization.

Best Practices and Production Recommendations

Security

  • Strong Passwords: Use strong, unique passwords for the admin account
  • Disable Anonymous Access: Set GF_AUTH_ANONYMOUS_ENABLED=false
  • Disable Sign-ups: Set GF_USERS_ALLOW_SIGN_UP=false
  • Use HTTPS: Klutch.sh provides HTTPS by default for your deployed apps
  • Regular Updates: Keep Grafana updated by periodically updating the image version in your Dockerfile
  • Secret Management: Store all sensitive credentials as environment variables, never in code

Performance

  • Resource Allocation: Monitor CPU and memory usage; scale compute resources as needed
  • Database Backend: For production, consider using PostgreSQL or MySQL instead of SQLite
  • Caching: Enable Grafana’s built-in caching for frequently accessed dashboards
  • Query Optimization: Optimize data source queries to reduce load and improve dashboard response times

Reliability

  • Backups: Regularly backup your persistent volume data
  • Health Checks: Monitor Grafana’s health endpoint at /api/health
  • High Availability: For critical deployments, run multiple instances with a shared database
  • Data Source Redundancy: Configure backup data sources where applicable

Monitoring

  • Self-Monitoring: Use Grafana to monitor Grafana’s own metrics
  • Log Analysis: Review Grafana logs regularly for errors or performance issues
  • User Activity: Monitor user access patterns and dashboard usage

Scalability

  • Instance Scaling: Start with 1 instance and scale horizontally based on concurrent user load
  • Vertical Scaling: Increase CPU and memory for data-intensive dashboards
  • Plugin Management: Only install necessary plugins to reduce resource usage
  • Dashboard Optimization: Use efficient queries and avoid excessive panel counts

Monitoring and Logging

Accessing Logs

  1. Navigate to your Grafana app in the Klutch.sh dashboard.

  2. Go to the Logs section to view real-time application logs.

  3. Monitor for errors, warnings, or performance issues.

Metrics to Monitor

  • CPU Usage: Should typically stay below 70% for good performance
  • Memory Usage: Monitor for memory leaks or excessive consumption
  • Response Times: Dashboard load times should be under 2 seconds
  • Error Rates: Watch for authentication failures or data source connection errors
  • Active Users: Track concurrent user sessions

Troubleshooting Common Issues

Grafana Won’t Start

  • Verify environment variables are correctly set
  • Check logs for database connection errors
  • Ensure persistent volume is properly mounted
  • Verify the Dockerfile builds successfully

Can’t Connect to Data Sources

  • Verify data source URLs are correct and accessible
  • Check authentication credentials
  • Ensure firewall rules allow connections
  • Test connectivity from Grafana container to data source

Dashboards Not Persisting

  • Verify persistent volume is mounted to /var/lib/grafana
  • Check database configuration and connectivity
  • Ensure sufficient disk space in the volume

Performance Issues

  • Review dashboard query efficiency
  • Increase compute resources (CPU/RAM)
  • Enable Grafana caching
  • Optimize data source queries
  • Consider using a dedicated database backend

Plugin Installation Failures

  • Verify plugin name is correct
  • Check internet connectivity during build
  • Try installing plugins using environment variables
  • Review build logs for specific error messages

Upgrading Grafana

To upgrade Grafana to a newer version:

  1. Update the version tag in your Dockerfile:

    FROM grafana/grafana:10.3.0

  2. Commit and push the changes to GitHub:

    Terminal window
    git add Dockerfile
    git commit -m "Upgrade Grafana to 10.3.0"
    git push origin main

  3. Klutch.sh will automatically detect the changes and trigger a new deployment.

  4. Monitor the deployment logs to ensure the upgrade completes successfully.

  5. Test your dashboards and data sources after the upgrade.

Important: Always review the Grafana release notes before upgrading to understand breaking changes or new features.

Advanced Configuration

Using External Database

For production deployments, using an external PostgreSQL or MySQL database is recommended:

  1. Deploy a database instance (can be on Klutch.sh or an external provider)
  2. Set the database environment variables as shown in Step 7
  3. Grafana will automatically create the necessary schema on first startup

Custom Plugins

To use custom or third-party plugins:

FROM grafana/grafana:latest


# Install plugins from zip files
COPY ./plugins /var/lib/grafana/plugins


# Or install from Grafana plugin registry
RUN grafana-cli plugins install <plugin-id>


EXPOSE 3000

OAuth Authentication

Configure OAuth for enterprise authentication:

Terminal window
GF_AUTH_GENERIC_OAUTH_ENABLED=true
GF_AUTH_GENERIC_OAUTH_NAME=OAuth
GF_AUTH_GENERIC_OAUTH_CLIENT_ID=your-client-id
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=your-client-secret
GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://your-oauth-provider/authorize
GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://your-oauth-provider/token
GF_AUTH_GENERIC_OAUTH_API_URL=https://your-oauth-provider/userinfo

LDAP Integration

For LDAP authentication, create an ldap.toml configuration file and reference it:

Terminal window
GF_AUTH_LDAP_ENABLED=true
GF_AUTH_LDAP_CONFIG_FILE=/etc/grafana/ldap.toml

Resources

Conclusion

Deploying Grafana on Klutch.sh provides you with a powerful, scalable platform for monitoring and observability. With automated builds from your Dockerfile, persistent storage for your dashboards, and flexible configuration options, you can create a robust monitoring solution that grows with your needs.

By following this guide, you’ve learned how to:

  • Deploy Grafana using a Dockerfile on Klutch.sh
  • Configure persistent storage for data and dashboards
  • Set up environment variables for secure configuration
  • Connect data sources and create visualizations
  • Implement best practices for production deployments
  • Scale and monitor your Grafana instance

For advanced setups, consider integrating with multiple data sources, implementing high availability with clustered deployments, or automating dashboard provisioning with your infrastructure as code workflows.

Start visualizing your data today with Grafana on Klutch.sh!