Install Loki + Promtail on VPS — Complete Log Aggregation Guide

Loki Promtail log aggregation on VPS Linux server

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

ComponentMinimumRecommended
RAM512 MB1 GB+
CPU1 vCPU2 vCPU
Disk10 GB50 GB+ (log storage)
OSUbuntu 20.04Ubuntu 22.04/24.04
Note: Loki and Promtail don't need to run on the same machine — this guide installs both on one server for simplicity.

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
Tip: Add a 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:

  1. Open Grafana → Connections → Add new data source
  2. Select Loki
  3. Set URL to http://localhost:3100
  4. 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'
Tip: If 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.