Grafana 12.3.3 (Amazon Linux 2023) AMI Administrator Guide

1. Quick Start Information

Connection Methods:

Access the instance via SSH using the ec2-user user. Use sudo to run commands requiring root privileges. To switch to the root user, use sudo su - root.

Install Information:

OS: Amazon Linux 2023
Grafana version: 12.3.3 (OSS)
Config file: /etc/grafana/grafana.ini
Data directory: /var/lib/grafana
Log directory: /var/log/grafana
Binary: /usr/share/grafana/bin/grafana

Grafana Service Management:

Start Grafana: sudo systemctl start grafana-server
Stop Grafana: sudo systemctl stop grafana-server
Restart Grafana: sudo systemctl restart grafana-server
Check status: sudo systemctl status grafana-server
Enable auto-start: sudo systemctl enable grafana-server

Quick Verification Commands:

Check version: grafana-server -v
Check port listening: sudo ss -tuln | grep 3000
Health check: curl -I http://localhost:3000/api/health
View logs: sudo journalctl -u grafana-server -f

Required Ports (Security Group):

Port	Protocol	Purpose	Required
22	TCP	SSH access	Yes

2. First Launch & Verification

Step 1: Verify Grafana is Running

Connect via SSH and check the service:

ssh -i your-key.pem ec2-user@YOUR_PUBLIC_IP
sudo systemctl status grafana-server --no-pager

Expected Output:

● grafana-server.service - Grafana instance
     Loaded: loaded (/usr/lib/systemd/system/grafana-server.service; enabled; ...)
     Active: active (running) since ...
   Main PID: xxxx (grafana)

Confirm port 3000 is listening:

sudo ss -tuln | grep 3000

Expected Output:

tcp   LISTEN 0      4096    *:3000    *:*

Run a health check:

curl -I http://localhost:3000/api/health

Expected Output:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

3. Architecture & Detailed Configuration

This AMI runs Grafana OSS 12.3.3 installed from the official Grafana RPM repository on Amazon Linux 2023. Grafana is a leading open-source observability and data visualization platform supporting dozens of data sources including Prometheus, InfluxDB, MySQL, PostgreSQL, CloudWatch, and more.

Installation Architecture:

[Grafana Official RPM Repository]
https://rpm.grafana.com
         ↓
[grafana 12.3.3 package]
/usr/share/grafana/bin/grafana → main binary
         ↓
[Configuration]
/etc/grafana/grafana.ini → main config
/var/lib/grafana/        → SQLite database + plugins
/var/log/grafana/        → application logs
         ↓
[Systemd Service]
grafana-server.service → Auto-start on boot
         ↓
[Listening on port 3000]

Key Design Decisions:

Official Grafana RPM repo: Uses rpm.grafana.com with GPG verification — ensures authentic, signed packages
dnf clean + makecache: Clears stale cache before install to prevent repository sync issues on AL2023
Auto-start enabled: grafana-server.service starts automatically on every boot
SQLite backend: Default embedded database — zero additional setup required for standalone deployments

3.1. Repository Configuration File

File Location: /etc/yum.repos.d/grafana.repo

Complete Contents:

[grafana]
name=Grafana OSS
baseurl=https://rpm.grafana.com
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://rpm.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt

How This Works:

repo_gpgcheck=1: Verifies the repository metadata signature (in addition to individual packages)
gpgcheck=1: Verifies each downloaded RPM package against the GPG key
gpgkey: Points to Grafana's official signing key — downloaded at install time
sslverify=1 + sslcacert: Enforces TLS verification of the repo server using the system CA bundle

This double-verification (repo metadata + package) ensures the installed Grafana binary is authentic and untampered.

3.2. Main Configuration File

File Location: /etc/grafana/grafana.ini

Key Default Settings:

[server]
# The public facing domain name used to access grafana from a browser
domain = localhost
# The http port to use
http_port = 3000
# The full public facing url
root_url = %(protocol)s://%(domain)s:%(http_port)s/

[database]
# Default is sqlite3
type = sqlite3
path = grafana.db

[security]
# Default admin user credentials
admin_user = admin
admin_password = admin

[log]
mode = console file
level = info

How This Works:

http_port = 3000: Grafana listens on port 3000 by default
type = sqlite3: Uses an embedded SQLite database at /var/lib/grafana/grafana.db — no external database needed

To customize (e.g., change port or enable SMTP):

sudo nano /etc/grafana/grafana.ini
sudo systemctl restart grafana-server

4. How-To-Create: Reproduce This Environment

This section explains how this AMI was built, allowing you to reproduce the installation on any Amazon Linux 2023 system.

Step 1: Update the System

sudo dnf update -y

How This Works:

Ensures all system packages are current before adding new repositories, preventing dependency conflicts.

Step 2: Add Grafana Official RPM Repository

sudo tee /etc/yum.repos.d/grafana.repo > /dev/null << 'EOF'
[grafana]
name=Grafana OSS
baseurl=https://rpm.grafana.com
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://rpm.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
EOF

How This Works:

Creates a dnf repository definition file pointing to the official Grafana RPM server
Both the repository metadata and individual packages are GPG-verified
The sslcacert path references the system CA bundle included with Amazon Linux 2023

Step 3: Clear Cache and Install Grafana

sudo dnf clean all
sudo dnf makecache
sudo dnf install grafana -y

How This Works:

dnf clean all: Removes all cached package metadata and downloaded files — prevents stale or corrupt cache from causing installation failures
dnf makecache: Re-downloads fresh repository metadata, including the new Grafana repository — you should see "Grafana OSS" listed in the output
dnf install grafana: Installs the latest Grafana OSS package from the official repository

Why clean before install?

On Amazon Linux 2023, adding a new repository while stale cache exists can cause metadata errors. Cleaning and rebuilding the cache ensures the Grafana repo is properly indexed before installation.

Step 4: Start and Enable Grafana

sudo systemctl daemon-reload
sudo systemctl enable --now grafana-server

How This Works:

daemon-reload: Tells systemd to re-read all service unit files, including the newly installed grafana-server.service
enable --now: Enables the service for auto-start on boot AND starts it immediately in one command

Step 5: Verify Installation

grafana-server -v
sudo systemctl status grafana-server --no-pager
sudo ss -tuln | grep 3000
curl -I http://localhost:3000/api/health

Expected Results:

Version 12.3.3 (commit: 2a14494b2d6ab60f860d8b27603d0ccb264336f6, branch: release-12.3.3)

Active: active (running) ...

tcp   LISTEN 0   4096   *:3000   *:*

HTTP/1.1 200 OK

5. Using Grafana

5.1. Installing Plugins

# Install a plugin (example: clock panel)
sudo grafana-cli plugins install grafana-clock-panel

# List installed plugins
sudo grafana-cli plugins ls

# Restart after installing plugins
sudo systemctl restart grafana-server

6. Important File Locations

File Path	Purpose
`/etc/grafana/grafana.ini`	Main Grafana configuration file
`/etc/yum.repos.d/grafana.repo`	Grafana RPM repository definition
`/var/lib/grafana/grafana.db`	SQLite database (dashboards, users, data sources)
`/var/lib/grafana/plugins/`	Installed Grafana plugins
`/var/log/grafana/grafana.log`	Main application log
`/usr/share/grafana/bin/grafana`	Grafana server binary
`/usr/lib/systemd/system/grafana-server.service`	Systemd service file
`/var/run/grafana/grafana-server.pid`	Process ID file

7. Troubleshooting

Issue 1: Grafana Service Fails to Start

Symptoms:

$ sudo systemctl status grafana-server
Active: failed

Diagnosis:

sudo journalctl -u grafana-server -n 50 --no-pager
sudo tail -50 /var/log/grafana/grafana.log

Common Causes:

Port 3000 already in use:

sudo lsof -i :3000

Change the port in /etc/grafana/grafana.ini:

[server]
http_port = 3001

Corrupted SQLite database:

sudo mv /var/lib/grafana/grafana.db /var/lib/grafana/grafana.db.bak
sudo systemctl start grafana-server

Note: This resets all dashboards and settings.

Permission issue on data directory:

sudo chown -R grafana:grafana /var/lib/grafana
sudo chown -R grafana:grafana /var/log/grafana
sudo systemctl start grafana-server

Issue 2: Plugin Installation Fails

Symptoms:

Error: ✗ Failed to install plugin

Solution:

Check internet connectivity and try with verbose output:

sudo grafana-cli --debug plugins install grafana-clock-panel

If behind a proxy, configure it in /etc/grafana/grafana.ini:

[plugin.grafana-clock-panel]
# Set proxy if needed

Issue 3: Repository Metadata Error During Install

Symptoms:

Error: Failed to download metadata for repo 'grafana'

Solution:

Clear and rebuild the cache:

sudo dnf clean all
sudo dnf makecache
sudo dnf install grafana -y

8. Final Notes

Key Takeaways

Grafana OSS 12.3.3 installed from the official RPM repository with GPG verification
SQLite used as the embedded database — no external database setup needed
The installation is production-ready and AMI-optimized with auto-start enabled

Grafana Use Cases

Infrastructure Monitoring: Visualize CPU, memory, disk, and network metrics
Application Performance: Track response times, error rates, and throughput
AWS CloudWatch: Build dashboards for EC2, RDS, Lambda, and other AWS services
Business Analytics: Query databases and visualize business KPIs
Log Analytics: Integrate with Loki or Elasticsearch for log visualization
Alerting: Set thresholds and receive notifications via email, Slack, PagerDuty

Recommended Instance Types

Workload	Instance	Reason
Personal / Small team	t3.small	Low traffic, few dashboards
Team use	t3.medium	Multiple users, moderate dashboards
Large deployment	t3.large / m5.large	High query load, many panels
Enterprise	m5.xlarge+	Heavy concurrent users and plugins

Additional Resources

Grafana Documentation: https://grafana.com/docs/grafana/latest/
Grafana Dashboard Library: https://grafana.com/grafana/dashboards/
Grafana Plugin Catalog: https://grafana.com/grafana/plugins/
Grafana Community: https://community.grafana.com/

For support or questions, please contact the Easycloud team.

1. Quick Start Information​

2. First Launch & Verification​

Step 1: Verify Grafana is Running​

3. Architecture & Detailed Configuration​

3.1. Repository Configuration File​

3.2. Main Configuration File​

4. How-To-Create: Reproduce This Environment​

Step 1: Update the System​

Step 2: Add Grafana Official RPM Repository​

Step 3: Clear Cache and Install Grafana​

Step 4: Start and Enable Grafana​

Step 5: Verify Installation​

5. Using Grafana​

5.1. Installing Plugins​

6. Important File Locations​

7. Troubleshooting​

Issue 1: Grafana Service Fails to Start​

Issue 2: Plugin Installation Fails​

Issue 3: Repository Metadata Error During Install​

8. Final Notes​

Key Takeaways​

Grafana Use Cases​

Recommended Instance Types​

Additional Resources​

1. Quick Start Information

2. First Launch & Verification

Step 1: Verify Grafana is Running

3. Architecture & Detailed Configuration

3.1. Repository Configuration File

3.2. Main Configuration File

4. How-To-Create: Reproduce This Environment

Step 1: Update the System

Step 2: Add Grafana Official RPM Repository

Step 3: Clear Cache and Install Grafana

Step 4: Start and Enable Grafana

Step 5: Verify Installation

5. Using Grafana

5.1. Installing Plugins

6. Important File Locations

7. Troubleshooting

Issue 1: Grafana Service Fails to Start

Issue 2: Plugin Installation Fails

Issue 3: Repository Metadata Error During Install

8. Final Notes

Key Takeaways

Grafana Use Cases

Recommended Instance Types

Additional Resources