Install Loki + Promtail on VPS — Complete Log Aggregation Guide
Grafana Loki is a log aggregation system designed to work alongside Prometheus and Grafana. Rather than indexing every word in your logs, Loki indexes only labels (such as hostname, service, level), making it far more storage-efficient than Elasticsearch. Promtail is the agent that reads log files and ships them to Loki.
This guide walks you through installing Loki + Promtail on Ubuntu 22.04/24.04 VPS from scratch until you can browse logs in Grafana.
System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| RAM | 512 MB | 1 GB+ |
| CPU | 1 vCPU | 2 vCPU |
| Disk | 10 GB | 50 GB+ (log storage) |
| OS | Ubuntu 20.04 | Ubuntu 22.04/24.04 |
Step 1 — Prepare System and Download Loki
Update the system and create a dedicated Loki user:
sudo apt update && sudo apt upgrade -y
sudo useradd --system --no-create-home --shell /bin/false loki
sudo mkdir -p /etc/loki /var/lib/loki /var/log/loki
sudo chown -R loki:loki /var/lib/loki /var/log/loki
Download the latest Loki binary:
# Check latest version at https://github.com/grafana/loki/releases
LOKI_VER="3.3.2"
cd /tmp
wget "https://github.com/grafana/loki/releases/download/v${LOKI_VER}/loki-linux-amd64.zip"
unzip loki-linux-amd64.zip
sudo mv loki-linux-amd64 /usr/local/bin/loki
sudo chmod +x /usr/local/bin/loki
loki --version
Step 2 — Create Loki Configuration
sudo tee /etc/loki/loki-config.yaml << 'EOF'
auth_enabled: false
server:
http_listen_port: 3100
grpc_listen_port: 9096
common:
instance_addr: 127.0.0.1
path_prefix: /var/lib/loki
storage:
filesystem:
chunks_directory: /var/lib/loki/chunks
rules_directory: /var/lib/loki/rules
replication_factor: 1
ring:
kvstore:
store: inmemory
query_range:
results_cache:
cache:
embedded_cache:
enabled: true
max_size_mb: 100
schema_config:
configs:
- from: 2020-10-24
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
limits_config:
retention_period: 30d
compactor:
working_directory: /var/lib/loki/compactor
retention_enabled: true
EOF
Step 3 — Create Loki systemd Service
sudo tee /etc/systemd/system/loki.service << 'EOF'
[Unit]
Description=Loki Log Aggregation System
Documentation=https://grafana.com/docs/loki/
After=network.target
[Service]
User=loki
Group=loki
Type=simple
ExecStart=/usr/local/bin/loki -config.file=/etc/loki/loki-config.yaml
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal
SyslogIdentifier=loki
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable loki
sudo systemctl start loki
sudo systemctl status loki --no-pager
Step 4 — Install Promtail
Promtail is the log shipping agent that reads log files and forwards them to Loki:
PROMTAIL_VER="3.3.2"
cd /tmp
wget "https://github.com/grafana/loki/releases/download/v${PROMTAIL_VER}/promtail-linux-amd64.zip"
unzip promtail-linux-amd64.zip
sudo mv promtail-linux-amd64 /usr/local/bin/promtail
sudo chmod +x /usr/local/bin/promtail
# Create dedicated promtail user
sudo useradd --system --no-create-home --shell /bin/false promtail
sudo usermod -aG adm promtail # Allow reading /var/log files
Step 5 — Create Promtail Configuration
sudo mkdir -p /etc/promtail
sudo tee /etc/promtail/promtail-config.yaml << 'EOF'
server:
http_listen_port: 9080
grpc_listen_port: 0
positions:
filename: /tmp/positions.yaml
clients:
- url: http://localhost:3100/loki/api/v1/push
scrape_configs:
- job_name: syslog
static_configs:
- targets: [localhost]
labels:
job: syslog
__path__: /var/log/syslog
- job_name: auth
static_configs:
- targets: [localhost]
labels:
job: auth
__path__: /var/log/auth.log
- job_name: nginx
static_configs:
- targets: [localhost]
labels:
job: nginx
__path__: /var/log/nginx/access.log
- job_name: nginx_error
static_configs:
- targets: [localhost]
labels:
job: nginx_error
__path__: /var/log/nginx/error.log
- job_name: journal
journal:
max_age: 12h
labels:
job: systemd-journal
relabel_configs:
- source_labels: ['__journal__systemd_unit']
target_label: 'unit'
EOF
host: your-server-name label to each job's labels so you can filter by host in Grafana dashboards.Step 6 — Create Promtail systemd Service
sudo tee /etc/systemd/system/promtail.service << 'EOF'
[Unit]
Description=Promtail Log Agent
After=network.target loki.service
[Service]
User=promtail
Group=promtail
Type=simple
ExecStart=/usr/local/bin/promtail -config.file=/etc/promtail/promtail-config.yaml
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal
SyslogIdentifier=promtail
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable promtail
sudo systemctl start promtail
sudo systemctl status promtail --no-pager
Step 7 — Connect Grafana to Loki
If Grafana isn't installed yet, see the Prometheus + Grafana guide first. Then:
- Open Grafana → Connections → Add new data source
- Select Loki
- Set URL to
http://localhost:3100 - Click Save & test — should show "Data source connected"
Querying Logs with LogQL
LogQL is Loki's query language, similar to PromQL — common examples:
# View all nginx logs
{job="nginx"}
# Filter for HTTP 500 errors
{job="nginx"} |= "\" 5"
# Request rate per minute
rate({job="nginx"}[1m])
# Failed SSH logins
{job="auth"} |= "Failed password"
# Filter with regex
{job="syslog"} |~ "error|warning|critical"
# Count log entries by systemd unit
sum by (unit) (count_over_time({job="systemd-journal"}[5m]))
Verify Loki + Promtail Are Working
# Check Loki health
curl -s http://localhost:3100/ready
# List labels Loki has received
curl -s http://localhost:3100/loki/api/v1/labels
# Check Promtail scrape targets
curl -s http://localhost:9080/targets
# Follow Loki logs in real-time
sudo journalctl -u loki -f --no-pager
# Follow Promtail logs in real-time
sudo journalctl -u promtail -f --no-pager
# Query 5 most recent syslog entries via API
curl -G -s "http://localhost:3100/loki/api/v1/query" \
--data-urlencode 'query={job="syslog"}' \
--data-urlencode 'limit=5'
curl http://localhost:3100/ready returns ready, Loki is up and running. Once Promtail starts shipping logs, labels will appear at /loki/api/v1/labels.Troubleshooting Common Issues
Error: "permission denied" when Promtail reads /var/log
Promtail needs to be in the adm group to read system logs:
sudo usermod -aG adm promtail
# Verify group membership
id promtail
# Restart after fixing
sudo systemctl restart promtail
Error: "context deadline exceeded" when Promtail ships logs
Usually means Loki isn't ready yet or the port is blocked:
# Check if Loki is listening
ss -tlnp | grep 3100
# Check firewall rules
sudo ufw status
# If Loki and Promtail are on different machines, allow port 3100
sudo ufw allow from PROMTAIL_IP to any port 3100
Error: "invalid schema version" in Loki logs
Occurs when the config schema doesn't match the Loki version. Clear old data (only safe on fresh installs with no production data):
sudo systemctl stop loki
sudo rm -rf /var/lib/loki/*
sudo systemctl start loki
Loki using too much disk space
Set a retention period to automatically purge old logs:
# In /etc/loki/loki-config.yaml
limits_config:
retention_period: 7d # Keep 7 days
compactor:
working_directory: /var/lib/loki/compactor
retention_enabled: true # Required
sudo systemctl restart loki
Frequently Asked Questions
How does Loki differ from Elasticsearch?
Loki indexes only labels (metadata), not the full log content. This makes it significantly more RAM and disk efficient than Elasticsearch, making it ideal for smaller VPS instances. The tradeoff is more limited full-text search capability — if you need complex searches across massive log volumes, Elasticsearch may be a better fit.
Can Promtail collect logs from Docker containers?
Yes — set the path to /var/lib/docker/containers/*/*.log and add a pipeline stage to parse Docker's JSON log format. Alternatively, use the official Loki Docker logging driver, which ships logs directly without going through files.
Should I expose port 3100 to the internet?
No — if Promtail and Loki are on the same machine, use localhost. For multi-server setups, connect over a private network or VPN and restrict port 3100 to specific trusted IPs only. Loki has no authentication in its default configuration.