VPS Tutorials
Grafana Loki on a VPS (2026): Docker, Alloy, HTTPS, alerts and backups
Deploy Loki, Grafana and Alloy on Ubuntu with Docker and Caddy HTTPS. Collect container logs, configure 30-day retention and alerts, and verify private backups and recovery.

When a VPS runs websites, databases, a reverse proxy and several Docker services, ad hoc docker logs searches make it difficult to determine when a fault started, which containers it affects and whether errors are increasing.
This Ubuntu VPS guide builds a small centralized log platform:
- Loki stores and queries logs.
- Grafana provides search, visualization and alerts.
- Alloy discovers Docker containers and collects their logs.
- Caddy exposes Grafana over HTTPS.
- Loki Compactor applies a 30-day retention policy.
- Offline archives include configuration, data, checksums and a recovery drill.
The source pins Loki 3.7.6, Grafana 13.2.1 and Alloy 1.19.2. These are published releases from the source's timeframe, not a claim that they remain the newest secure versions. Review releases and breaking changes before selecting maintained production tags.
Loki mainly indexes labels rather than all log text, often using fewer resources than a comparable full-text search stack. It fits:
- Several Compose projects on one or a few VPS hosts.
- Queries by host, container or Compose service.
- Alerts on 5xx, failed logins or background-job errors.
- Hundreds of MB per day without a large search cluster.
- Teams already using Prometheus and Grafana.
OpenSearch may fit complex full-text analysis or security investigations better. For application exceptions, release versions and affected users, see the Sentry guide. Plain docker logs requires no new service, but offers weaker cross-service correlation, retention after rebuilds and alerts.
Grafana describes monolithic Loki for relatively small workloads, around 20 GB/day or less. That is architectural guidance, not a target or capacity guarantee for a cheap VPS. CPU, RAM, IOPS and query range can impose lower limits.
| Daily logs | Conservative starting point | Notes |
|---|---|---|
| Below 500 MB | 2 vCPU / 4 GB / 40 GB SSD | A few websites and jobs |
| 500 MB–2 GB | 4 vCPU / 8 GB / 100 GB SSD | Multiple application containers |
| 2–5 GB | 6–8 vCPU / 16 GB / 200 GB NVMe | Strict query and label controls |
For 1 GB/day and 30-day retention, budget at least 60–100 GB for Loki data/indexes, compaction, Docker's own logs and temporary backup space. Filesystem storage does not automatically delete logs when disk space runs low. Configure retention and disk alerts together.
Local Alloy/Loki/Grafana traffic remains within Docker networking. External traffic comes from large browser queries, off-host backups and remote collectors. Remote ingestion needs HTTPS, authentication and estimates of daily volume and egress charges.
Docker stdout/stderr flows through Alloy to Loki, then Grafana displays it behind Caddy. Loki 3100 and Grafana 3000 have host-loopback mappings in this example; neither is public. The original diagram is:
Docker 容器 stdout/stderr
|
v
Grafana Alloy --> Loki :3100(仅 Docker 内网)
|
v
Grafana :3000(仅 127.0.0.1)
|
v
Caddy HTTPS :443
Loki has no built-in authentication. Keep its API private; Caddy supplies public TLS only for Grafana.
Point a hostname such as logs.example.com at the VPS, then install the prerequisites:
sudo apt update
sudo apt install -y ca-certificates curl caddy
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
The source runs Docker's convenience installer. For production, inspect that script before execution or use Docker's official apt repository. Install openssl and ufw if they are absent. Reconnect SSH after changing group membership. Docker-group access effectively grants host administration privileges; keep it with trusted operators. Preserve key-based SSH access before disabling password authentication.
Allow SSH, HTTP and HTTPS:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status
Do not open 3000 or 3100. Grafana's binding to 127.0.0.1 adds a separate restriction. Confirm actual published ports as well as UFW/cloud rules.
sudo mkdir -p /opt/loki-stack/{loki,grafana/provisioning/datasources,alloy}
sudo chown -R "$USER":"$USER" /opt/loki-stack
cd /opt/loki-stack
openssl rand -base64 30
Store the generated password privately, then create .env:
umask 077
printf 'GRAFANA_ADMIN_USER=admin\nGRAFANA_ADMIN_PASSWORD=替换为刚才生成的密码\n' > .env
Replace the password placeholder inside that source command with the actual generated value before use. Do not leave the placeholder as the login password or commit the file.
chmod 600 .env
ls -l .env
Create /opt/loki-stack/loki/loki.yaml:
auth_enabled: false
server:
http_listen_port: 3100
common:
path_prefix: /loki
storage:
filesystem:
chunks_directory: /loki/chunks
rules_directory: /loki/rules
replication_factor: 1
ring:
instance_addr: 127.0.0.1
kvstore:
store: inmemory
schema_config:
configs:
- from: 2024-01-01
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
limits_config:
retention_period: 720h
ingestion_rate_mb: 8
ingestion_burst_size_mb: 16
max_query_length: 744h
compactor:
working_directory: /loki/compactor
retention_enabled: true
delete_request_store: filesystem
analytics:
reporting_enabled: false
This uses TSDB, schema v13 and a 24-hour index period. retention_period: 720h specifies 30 days, but retention also needs compactor.retention_enabled: true. Keep Compactor's working directory in persistent storage so pending deletion markers survive rebuilding.
For a smaller disk, choose 336h for 14 days before ingestion starts. Official documentation states retention changes are not retroactive for already-ingested logs. Shortening the setting is therefore not an immediate disk-recovery procedure. Expand storage or use a documented deletion workflow when necessary; do not manually remove active chunks/indexes.
Create /opt/loki-stack/grafana/provisioning/datasources/loki.yaml:
apiVersion: 1
datasources:
- name: Loki
uid: loki
type: loki
access: proxy
url: http://loki:3100
isDefault: true
editable: false
jsonData:
maxLines: 1000
http://loki:3100 is the internal Compose service address. localhost:3100 would point at Grafana's own container.
Create /opt/loki-stack/alloy/config.alloy:
discovery.docker "local" {
host = "unix:///var/run/docker.sock"
refresh_interval = "5s"
}
discovery.relabel "docker_logs" {
targets = discovery.docker.local.targets
rule {
source_labels = ["__meta_docker_container_name"]
regex = "/(.*)"
target_label = "container"
}
rule {
source_labels = ["__meta_docker_container_label_com_docker_compose_service"]
target_label = "service_name"
}
rule {
source_labels = ["__meta_docker_container_label_com_docker_compose_project"]
target_label = "compose_project"
}
}
loki.source.docker "local" {
host = "unix:///var/run/docker.sock"
targets = discovery.docker.local.targets
relabel_rules = discovery.relabel.docker_logs.rules
labels = {
host = "vps-01",
job = "docker",
}
forward_to = [loki.write.local.receiver]
}
loki.write "local" {
endpoint {
url = "http://loki:3100/loki/api/v1/push"
}
}
The configuration retains container, service_name, compose_project, host and job. Avoid request/user IDs, full URL paths and timestamps as labels: they create high cardinality.
Alloy accesses /var/run/docker.sock. A :ro bind mount does not make the Docker API read-only; a socket client has powerful host-level capabilities. Use trusted pinned images, protect the configuration and run trusted workloads on this host.
Create /opt/loki-stack/compose.yaml:
services:
loki:
image: grafana/loki:3.7.6
command: -config.file=/etc/loki/loki.yaml
restart: unless-stopped
ports:
- "127.0.0.1:3100:3100"
volumes:
- ./loki/loki.yaml:/etc/loki/loki.yaml:ro
- loki-data:/loki
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:3100/ready"]
interval: 15s
timeout: 5s
retries: 10
logging:
options:
max-size: "10m"
max-file: "3"
grafana:
image: grafana/grafana:13.2.1
restart: unless-stopped
depends_on:
loki:
condition: service_healthy
ports:
- "127.0.0.1:3000:3000"
environment:
GF_SECURITY_ADMIN_USER: "${GRAFANA_ADMIN_USER}"
GF_SECURITY_ADMIN_PASSWORD: "${GRAFANA_ADMIN_PASSWORD}"
GF_USERS_ALLOW_SIGN_UP: "false"
GF_AUTH_ANONYMOUS_ENABLED: "false"
GF_SERVER_ROOT_URL: "https://logs.example.com"
volumes:
- grafana-data:/var/lib/grafana
- ./grafana/provisioning:/etc/grafana/provisioning:ro
logging:
options:
max-size: "10m"
max-file: "3"
alloy:
image: grafana/alloy:v1.19.2
command:
- run
- --storage.path=/var/lib/alloy/data
- /etc/alloy/config.alloy
restart: unless-stopped
depends_on:
loki:
condition: service_healthy
volumes:
- ./alloy/config.alloy:/etc/alloy/config.alloy:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- alloy-data:/var/lib/alloy/data
logging:
options:
max-size: "10m"
max-file: "3"
volumes:
loki-data:
grafana-data:
alloy-data:
The logging limits rotate the stack's own Docker logs. Without them, those files can fill the root partition even when Loki retention is correct. See the production Compose guide.
The source checks configuration with:
cd /opt/loki-stack
docker compose config --quiet
docker run --rm \
-v "$PWD/loki/loki.yaml:/etc/loki/loki.yaml:ro" \
grafana/loki:3.7.6 \
-config.file=/etc/loki/loki.yaml -verify-config
docker run --rm \
-v "$PWD/alloy/config.alloy:/etc/alloy/config.alloy:ro" \
grafana/alloy:v1.19.2 \
fmt --check /etc/alloy/config.alloy
Alloy's documented format-test flag is --test, not the source's --check. Formatting checks syntax/formatting, not component validity; run validate as well:
docker run --rm \
-v "$PWD/alloy/config.alloy:/etc/alloy/config.alloy:ro" \
grafana/alloy:v1.19.2 fmt --test /etc/alloy/config.alloy
docker run --rm \
-v "$PWD/alloy/config.alloy:/etc/alloy/config.alloy:ro" \
grafana/alloy:v1.19.2 validate /etc/alloy/config.alloy
The pinned Loki Dockerfile uses a distroless image without wget, a shell or du. Its original healthcheck therefore fails and blocks the two service_healthy dependencies. Before startup, create this automatically loaded compose.override.yaml, then use an actual host HTTP readiness check:
set -eu
cd /opt/loki-stack
cat >compose.override.yaml <<'YAML'
services:
loki:
healthcheck:
disable: true
grafana:
depends_on:
loki:
condition: service_started
alloy:
depends_on:
loki:
condition: service_started
YAML
docker compose config --quiet
docker compose pull
docker compose up -d loki
LOKI_READY=0
for LOKI_ATTEMPT in $(seq 1 60); do
if curl -fsS http://127.0.0.1:3100/ready; then
LOKI_READY=1
break
fi
sleep 2
done
test "$LOKI_READY" -eq 1
docker compose up -d grafana alloy
docker compose ps
Do not treat a started container as healthy. Keep host monitoring of Loki readiness after deployment. The original inspection commands remain useful after the corrections:
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 loki alloy grafana
curl -fsS http://127.0.0.1:3100/ready
curl -fsS http://127.0.0.1:3000/api/health
Loki should report ready; Grafana's health JSON should report database status ok. Allow initial startup time before concluding a probe failed.
Edit /etc/caddy/Caddyfile with the actual hostname, matching Grafana's root URL:
logs.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
}
}
Validate and reload:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://logs.example.com/login
Caddy obtains and renews certificates. See the Caddy HTTPS guide for proxy troubleshooting.
After first login, create a separate administrator and verify it before disabling or renaming admin. For shared use, prefer an identity provider with MFA over a shared administrator password.
The original temporary test is:
docker run --rm alpine:3.22 sh -c \
'echo "loki-smoke-test level=info"; echo "sample failure level=error" >&2'
It exits and removes itself before the 5-second discovery refresh can see it. Use a temporary container that stays alive through discovery:
docker run --rm alpine:3.22 sh -c \
'echo "loki-smoke-test level=info"; echo "sample failure level=error" >&2; sleep 20'
Then open Drilldown > Logs or Explore, choose Loki and query:
{job="docker"} |= "loki-smoke-test"
Useful queries include:
{compose_project="myapp"}
{service_name="nginx"} |~ "(?i)error|critical|panic"
sum by (service_name) (
count_over_time({job="docker"} |~ "(?i)error|exception" [5m])
)
topk(10, sum by (service_name) (
rate({job="docker"}[5m])
))
Narrow the time range and stable labels before filtering with |= or |~. Avoid routine full-regex searches across every container for 30 days.
Good labels usually have a small stable set of values:
- Hostname.
- Environment, such as production/staging.
- Compose project.
- Service name.
- Container name.
IP addresses, order/user/request IDs, complete URLs and random task IDs belong in log text, parsed or filtered at query time. If stream count rises continually, inspect dynamic Docker labels and Alloy relabeling. Check that each proposed label has bounded, stable values.
Grafana-managed alerts can evaluate Loki expressions, for example:
sum by (service_name) (
count_over_time({job="docker"} |~ "(?i)error|exception|panic" [5m])
) > 20
This counts matching lines over five minutes; it is not a percentage error rate. Set a five-minute pending period to suppress brief deployment spikes. Configure actual contact points and notification policies for email, Slack, Telegram or a webhook.
Observe a week of normal behavior and set service-specific thresholds rather than alerting on every occurrence of “error.” Combine logs with CPU, memory, disk and availability from the Prometheus/Grafana guide.
Also alert on:
- Root/Docker data disk usage above 80%.
- Loki restarts or failed
/ready. - Alloy dropped entries, write failures or repeated reconnects.
- Do not log passwords, cookies, authorization headers, API keys or full payment details.
- Redact at the application first; collector regex filtering is supplementary.
- Keep Loki 3100 and Alloy debugging private.
- Limit administrators and give ordinary readers Viewer access.
- Review data-source proxy and plugin permissions.
- Encrypt off-host backups.
auth_enabled: false fits only this closed single-host network. Remote ingestion needs an authenticated TLS reverse proxy or tenant-aware gateway. Do not make 3100 public.
Pause the stack and archive the three volumes and configuration. The source /usr/local/sbin/backup-loki-stack.sh is:
#!/usr/bin/env bash
set -Eeuo pipefail
STACK_DIR="/opt/loki-stack"
BACKUP_ROOT="/var/backups/loki-stack"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
TARGET="$BACKUP_ROOT/loki-stack-$STAMP.tar.gz"
mkdir -p "$BACKUP_ROOT"
cd "$STACK_DIR"
docker compose stop alloy grafana loki
trap 'docker compose start loki grafana alloy' EXIT
LOKI_VOL="$(docker inspect loki-stack-loki-1 \
--format '{{range .Mounts}}{{if eq .Destination "/loki"}}{{.Name}}{{end}}{{end}}')"
GRAFANA_VOL="$(docker inspect loki-stack-grafana-1 \
--format '{{range .Mounts}}{{if eq .Destination "/var/lib/grafana"}}{{.Name}}{{end}}{{end}}')"
ALLOY_VOL="$(docker inspect loki-stack-alloy-1 \
--format '{{range .Mounts}}{{if eq .Destination "/var/lib/alloy/data"}}{{.Name}}{{end}}{{end}}')"
test -n "$LOKI_VOL"
test -n "$GRAFANA_VOL"
test -n "$ALLOY_VOL"
docker run --rm \
-v "$LOKI_VOL:/source/loki:ro" \
-v "$GRAFANA_VOL:/source/grafana:ro" \
-v "$ALLOY_VOL:/source/alloy:ro" \
-v "$STACK_DIR:/source/config:ro" \
-v /etc/caddy:/source/caddy:ro \
-v "$BACKUP_ROOT:/backup" \
alpine:3.22 \
tar -czf "/backup/$(basename "$TARGET")" -C /source \
loki grafana alloy config caddy
sha256sum "$TARGET" > "$TARGET.sha256"
find "$BACKUP_ROOT" -type f -mtime +14 -delete
Its generated-container-name assumptions and permissive default file creation need correction. Use this root-run version for the documented named-volume layout. It resolves mounted volumes from actual service IDs, protects credentials and arms restart handling before stopping:
#!/usr/bin/env bash
set -euo pipefail
test "$(id -u)" -eq 0
cd /opt/loki-stack
umask 077
exec 9>/run/lock/loki-stack-backup.lock
flock -n 9
LOKI_BACKUP="/var/backups/loki-stack/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$LOKI_BACKUP"
LOKI_CID="$(docker compose ps -q loki)"
GRAFANA_CID="$(docker compose ps -q grafana)"
ALLOY_CID="$(docker compose ps -q alloy)"
test -n "$LOKI_CID" && test -n "$GRAFANA_CID" && test -n "$ALLOY_CID"
LOKI_VOL="$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/loki"}}{{.Name}}{{end}}{{end}}' "$LOKI_CID")"
GRAFANA_VOL="$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/var/lib/grafana"}}{{.Name}}{{end}}{{end}}' "$GRAFANA_CID")"
ALLOY_VOL="$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/var/lib/alloy/data"}}{{.Name}}{{end}}{{end}}' "$ALLOY_CID")"
test -n "$LOKI_VOL" && test -n "$GRAFANA_VOL" && test -n "$ALLOY_VOL"
docker volume inspect "$LOKI_VOL" "$GRAFANA_VOL" "$ALLOY_VOL" >/dev/null
docker pull alpine:3.22 >/dev/null
trap 'docker compose start loki grafana alloy >&2' EXIT
docker compose stop alloy grafana loki
docker run --rm \
-v "$LOKI_VOL:/source/loki:ro" \
-v "$GRAFANA_VOL:/source/grafana:ro" \
-v "$ALLOY_VOL:/source/alloy:ro" \
-v "$PWD:/source/config:ro" \
-v /etc/caddy:/source/caddy:ro \
-v "$LOKI_BACKUP:/backup" \
alpine:3.22 tar -czf /backup/loki-stack.tar.gz -C /source \
loki grafana alloy config caddy
(
cd "$LOKI_BACKUP"
sha256sum loki-stack.tar.gz >loki-stack.tar.gz.sha256
sha256sum -c loki-stack.tar.gz.sha256
)
docker compose start loki grafana alloy
trap - EXIT
touch "$LOKI_BACKUP/COMPLETE"
chmod -R go-rwx "$LOKI_BACKUP"
printf 'Backup complete: %s\n' "$LOKI_BACKUP"
Enable and test the script:
sudo chmod 700 /usr/local/sbin/backup-loki-stack.sh
sudo /usr/local/sbin/backup-loki-stack.sh
sudo ls -lh /var/backups/loki-stack
sudo sha256sum -c /var/backups/loki-stack/*.sha256
The original assumed the project name loki-stack; docker compose ps and docker inspect help inspect the actual deployment. The replacement avoids relying on generated names and includes the automatic override. Only accept an archive marked COMPLETE with verified checksums; monitoring must still confirm restart succeeded.
A pause may cause missed collection if Docker rotates unread logs before Alloy returns. If uninterrupted ingestion is required, choose object storage and a tested consistent-backup design rather than running tar over active files. See the backup/recovery drill for off-host protection.
On a temporary isolated VPS:
- Install compatible Docker/Caddy and the same application versions first.
- Verify the archive SHA-256.
- Extract configuration/data privately.
- Create three new volumes and restore their respective data.
- Check volume names and the test hostname in
compose.yaml, including its override. - Start Loki, Grafana and Alloy.
- Query a known pre-backup log entry.
- Verify data sources, alerts and users.
The source extraction example is:
sha256sum -c loki-stack-20260906T020000Z.tar.gz.sha256
mkdir -p /tmp/loki-restore
tar -xzf loki-stack-20260906T020000Z.tar.gz -C /tmp/loki-restore
find /tmp/loki-restore -maxdepth 2 -type d -print
Use the actual backup filename, not that historical date. Test historical queries, login, alert configuration and fresh ingestion; container startup alone does not prove recovery.
For a Grafana patch/minor update:
cd /opt/loki-stack
sudo /usr/local/sbin/backup-loki-stack.sh
docker compose pull grafana
docker compose up -d grafana
docker compose ps
docker compose logs --tail=100 grafana
curl -fsS http://127.0.0.1:3000/api/health
Read release notes, back up and change one image tag. Verify login, data sources, queries and alerts before updating the next component.
If an upgrade migrates Grafana's database or Loki's format, an image downgrade alone may be unsafe. Restore the matching pre-upgrade snapshot. Follow backup, pull, single-component update, health checks, real queries and observation before continuing.
docker compose exec grafana \
wget -qO- http://loki:3100/ready
docker compose logs --tail=200 loki grafana
Use http://loki:3100 rather than localhost in the data source.
docker compose logs --tail=200 alloy
docker compose exec alloy ls -l /var/run/docker.sock
docker inspect loki-stack-alloy-1 --format '{{json .Mounts}}'
Check the socket mount, loaded configuration and whether the host uses a nonstandard socket location.
docker system df
docker compose exec loki du -sh /loki/*
docker compose logs --tail=300 loki | grep -iE 'compactor|retention|delete|error'
The du command in that source example cannot run in the pinned distroless Loki image. Inspect the data mount with a separate read-only tools container or host storage monitoring. Verify retention_enabled, the 24-hour index and persistent Compactor directory. Deletion is delayed and retention changes are not retroactive; do not wait until 95% disk usage.
Shorten the range and add service_name, compose_project or host. Check high-cardinality labels. Thirty-day regex searches over all services should not be routine on a single VPS.
curl -fsS http://127.0.0.1:3000/api/health
sudo journalctl -u caddy -n 100 --no-pager
sudo caddy validate --config /etc/caddy/Caddyfile
If local 3000 is healthy, check the public hostname, certificate and reverse-proxy target.
- DNS and public 80/443 work.
- 3000/3100 are private.
- Loki, Grafana and Alloy are pinned.
- Effective Compose, Loki and Alloy validation pass.
- Admin credentials changed; anonymous access disabled.
- A test entry is found with LogQL.
- Labels contain no dynamic user/request IDs.
- Retention and disk alerts are enabled.
- Error alerts reach a real notification channel.
- Backups include all three volumes and configuration.
- An isolated restore succeeds.
- Updates change one component at a time.
4 GB is a practical starting point for modest Docker logs, not a hard minimum. Query ranges/concurrency, ingestion and labels determine memory demand. A 2 GB machine can be an experiment but is a poor choice for important workloads plus long log searches.
Not for every workload. Loki filters labels and scans log text with relatively low indexing cost. Full-text indexing, complex aggregation and security analysis may fit Elasticsearch/OpenSearch better. Choose by query needs.
Compactor deletion is asynchronous, and the official retention policy changes are not retroactive. Also check the 24-hour TSDB index period, persistent marker storage and Compactor errors. Plan storage headroom rather than relying on instant cleanup.
Yes, through an authenticated TLS gateway/proxy with source restrictions and traffic planning. Multi-tenant setups also need trusted tenant-header handling and authorization. Keep 3100 private.
Use Alloy for new deployments. It combines discovery, relabeling, logs, metrics and traces. Compare existing Promtail stages with official migration documentation before changing a collector.
This filesystem archive needs a pause for consistency. Continuous service needs compatible object storage/versioning or tested storage snapshots with their own consistency and recovery procedure.