Grafana Alloy on a VPS: install it and migrate from Promtail

Why replace Promtail with Alloy now

What a single agent changes on your server

• One service to watch — logs and metrics go through the same alloy process, with a single journal to read when something breaks.
• Updates that still arrive — Alloy is published in Grafana's apt and rpm repositories: an apt upgrade keeps it current like the rest of the system.
• A tooled migration — the alloy convert command translates an existing Promtail configuration and produces a report of what it could not convert.
• Built-in system metrics — the prometheus.exporter.unix component replaces node_exporter without an extra binary or port to open.
• A local debugging interface — the UI on port 12345 shows the component graph and their values, reachable through an SSH tunnel.
• Output to your own stack or to Grafana Cloud — the same file sends to a self-hosted Loki or to a managed service by changing one URL.

Sized prerequisites for Alloy on a VPS

Install Alloy and connect logs and metrics

1. 01

   Add the Grafana repository on Debian or Ubuntu

   sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install alloy

2. 02

   Or install it on AlmaLinux and Rocky Linux

   Import the key with wget -q -O gpg.key https://rpm.grafana.com/gpg.key then sudo rpm --import gpg.key. Create /etc/yum.repos.d/grafana.repo with baseurl=https://rpm.grafana.com, repo_gpgcheck=1, gpgcheck=1 and enabled=1, as the Alloy Linux installation page shows, then run sudo dnf install alloy.

3. 03

   Start the service and check its user

   sudo systemctl enable --now alloy
sudo systemctl status alloy
systemctl cat alloy | grep User

   The last command should print User=alloy. The package does not set a Group=: read access therefore comes from that user's secondary groups, which matters for what follows.

4. 04

   Declare the log destination

   Open /etc/alloy/config.alloy and add the sender to Loki:

   loki.write "default" {
endpoint {
url = "http://127.0.0.1:3100/loki/api/v1/push"
}
}

   Replace the address with your Loki's. If it is remote, use HTTPS and a basic_auth block.

5. 05

   Collect journald and log files

   loki.source.journal "system" {
forward_to = [loki.write.default.receiver]
labels = {"job" = "systemd-journal"}
}
local.file_match "nginx" {
path_targets = [{"__path__" = "/var/log/nginx/*.log", "job" = "nginx"}]
}
loki.source.file "nginx" {
targets = local.file_match.nginx.targets
forward_to = [loki.write.default.receiver]
}

   By default, the journal source reads /var/log/journal and /run/log/journal, and only goes back seven hours on first start.

6. 06

   Collect system metrics

   prometheus.exporter.unix "node" { }
prometheus.scrape "node" {
targets = prometheus.exporter.unix.node.targets
forward_to = [prometheus.remote_write.default.receiver]
}
prometheus.remote_write "default" {
endpoint {
url = "http://127.0.0.1:9090/api/v1/write"
}
}

   If node_exporter was already running on the machine, stop it after the switch so the same series are not collected twice.

7. 07

   Validate before reloading

   sudo alloy validate /etc/alloy/config.alloy
sudo systemctl reload alloy
sudo journalctl -u alloy -f

   A syntax error or a wrongly referenced component is reported by validate before the service loads the configuration.

8. 08

   Grant read access

   id alloy should list the adm and systemd-journal groups. The package adds them when they exist; after a binary install or a removed group, restore them with sudo usermod -aG adm,systemd-journal alloy then sudo systemctl restart alloy. For an application folder owned by another user, the documentation prefers an ACL to one more group: sudo setfacl -R -m u:alloy:rx /var/log/monapp and sudo setfacl -R -d -m u:alloy:rx /var/log/monapp.

9. 09

   Check end to end, then connect your dashboards

   Write a marker line with logger -t alloy-test "ligne de test alloy", then look for it in Grafana, Explore tab, with the query {job="systemd-journal"} |= "ligne de test alloy". On the metrics side, the node_load1 query should return a series for your VPS. Both answer: reuse the dashboards from our Grafana and Prometheus guide, which read the same node_* series.

Alloy and Docker: read containers without opening everything

Migrating from Promtail: the real risk is positions

Migrate a Promtail configuration without loss or duplicates

1. 10

   Locate the configuration and the positions file

   Open the Promtail configuration, often /etc/promtail/config.yml, and note the value of positions.filename. In a Docker Compose install, this file lives in a volume: note its real path on the host.

2. 11

   Convert with a report

   alloy convert --source-format=promtail --report=/tmp/promtail-report.txt --output=/tmp/promtail.alloy /etc/promtail/config.yml

   Read the report first. The --bypass-errors option forces a partial conversion, but the documentation warns that behavior may then differ from the original.

3. 12

   Check that the alloy user can read the old file

   grep legacy_positions_file /tmp/promtail.alloy
sudo -u alloy cat /var/lib/promtail/positions.yaml

   Adapt the path to the one noted above. If the second command fails, copy the file into a folder readable by alloy and fix the path in the converted configuration.

4. 13

   Stop Promtail before starting Alloy

   sudo systemctl stop promtail, or docker compose stop promtail for a container stack. Promtail then writes its last positions, and no line is sent twice during the switch.

5. 14

   Switch the configuration

   Copy the converted blocks into /etc/alloy/config.alloy, run sudo alloy validate /etc/alloy/config.alloy, then sudo systemctl restart alloy. Immediately check sudo journalctl -u alloy | grep -i positions: no error reading legacy positions file line should appear.

6. 15

   Monitor for a week, then uninstall

   Compare log volume in Grafana before and after the switch, and follow Alloy's loki_write_sent_entries_total counter. Keep the Promtail configuration a few days, then sudo systemctl disable promtail and remove the package or the Compose service.

Promtail and Alloy, side by side

Scroll the table

Post-install configuration: UI, secrets and storage

Troubleshooting: the errors Alloy does not shout about

Error messages and fixes

• The journal source starts, but no line arrives — the loki.source.journal documentation says it: without the adm and systemd-journal groups, the component starts without error and collects nothing. Fix it with sudo usermod -aG adm,systemd-journal alloy, then restart the service, because an added group only takes effect at the next launch.
• failed to tail the file: open /var/log/…: permission denied — the file exists but alloy cannot read it. Grant an ACL on the folder with setfacl -R -m u:alloy:rx and its -d variant for files later created by rotation.
• No message, no line for a whole folder — grafana/alloy issue #6542 describes logs never sent without any error. A maintainer confirms there that an unreadable file is logged, but an inaccessible folder is not. Test with sudo -u alloy ls /var/log/monapp.
• error reading legacy positions file … permission denied — Alloy did not read Promtail's positions and may re-send everything from the beginning (issue #5493). Stop the service, make the file readable for alloy, then start again.
• failed to identify the read-write layer ID … mount-id: permission denied — an error from the cAdvisor component under systemd (issue #4068). The docker group is not enough; users report that a drop-in with AmbientCapabilities=CAP_DAC_READ_SEARCH and CapabilityBoundingSet=CAP_DAC_READ_SEARCH solves it without running the service as root. It is a community workaround, to test before rolling it out.
• The UI is green, but Grafana stays empty — check loki_write_sent_entries_total and the test line written by logger. If the counter stalls, the failure is upstream, on the source side.

An up-to-date agent on a server that belongs to you