Perses

Search the Azure Marketplace for Perses, choose the plan, and create the VM.

In the networking step, attach a network security group (NSG) that allows inbound TCP 22 (SSH) and TCP 80 (the UI, behind Basic Auth) from your client networks only. For production, put a TLS reverse proxy in front of port 80 (Step 16).

Run the following commands, replacing the values in angle brackets:

RG="perses-prod"; LOCATION="eastus"; VM_NAME="perses-01" IMAGE_URN="sac1647283583153:perses-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name ps-vnet --address-prefix 10.108.0.0/16 --subnet-name ps-subnet --subnet-prefix 10.108.1.0/24 az network nsg create -g "$RG" --name ps-nsg az network nsg rule create -g "$RG" --nsg-name ps-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name ps-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:perses-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name ps-vnet --subnet ps-subnet --nsg ps-nsg --public-ip-sku Standard

Connect to the VM as azureuser:

ssh azureuser@<vm-ip>

perses.service, nginx.service and perses-firstboot.service all start automatically on first boot.

Check the services, the first-boot marker and the listening ports:

sudo systemctl is-active perses nginx perses-firstboot
sudo test -f /var/lib/sac/data/perses-firstboot.done && echo FIRSTBOOT_DONE
sudo ss -tlnp | grep -E ':80 |8080'

In the expected output, all three services are active. nginx is bound to the public port 80, and Perses is bound to loopback 127.0.0.1:8080 only:

active active active FIRSTBOOT_DONE LISTEN 0 4096 127.0.0.1:8080 0.0.0.0:* users:(("perses",...)) LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("nginx",...))

The web UI is protected by an HTTP Basic Auth password that is generated uniquely on this VM's first boot. Read it, along with the URL and username, from the root-only credentials file:

sudo cat /root/perses-credentials.txt

The file holds the username (admin), this VM's URL and the per-VM password. No credential is baked into the image, and every VM gets its own. Perses itself is bound to loopback, so the only way in is through the nginx password gate:

PERSES_URL=http://<vm-ip>/ PERSES_USERNAME=admin PERSES_PASSWORD=<PERSES_PASSWORD>

An unauthenticated request is rejected, and Perses listens only on loopback.

Open http://<vm-ip>/ in a browser and sign in as admin with the password from Step 5.

The home page lists your projects and recently viewed dashboards. The demo project seeded by the image is already there.

Click the demo project. A project groups dashboards, variables, datasources and secrets. The seeded Welcome dashboard is listed and ready to open.

Open the Welcome dashboard. It renders the sample Markdown panels seeded by the image, so the interface is populated the moment the VM boots. This is the dashboard view you will use for your own metrics, traces, logs and profiles.

Click Edit to open the dashboard in edit mode. Add panels and panel groups, wire them to variables and datasources, and save. This is the same dashboard model you can also manage as code with percli (Step 12).

Everything in the UI is also available through the JSON REST API, behind the same per-VM password. List your projects and a project's dashboards:

curl -s -u admin:<PERSES_PASSWORD> http://127.0.0.1/api/v1/projects | jq '[.[].metadata.name]'
curl -s -u admin:<PERSES_PASSWORD> http://127.0.0.1/api/v1/projects/demo/dashboards | jq '[.[].metadata.name]'

The calls return the seeded demo project and its welcome dashboard:

[ "demo" ] [ "welcome" ]

You can create resources entirely through the API. This example creates a myteam project and a first dashboard with a Markdown panel, then reads the dashboard back:

PW='<PERSES_PASSWORD>' curl -s -u admin:$PW -H 'Content-Type: application/json' -X POST http://127.0.0.1/api/v1/projects \
  -d '{"kind":"Project","metadata":{"name":"myteam"}}' -o /dev/null -w 'create project: %{http_code}\n' curl -s -u admin:$PW -H 'Content-Type: application/json' -X POST http://127.0.0.1/api/v1/projects/myteam/dashboards \
  -d '{"kind":"Dashboard","metadata":{"name":"first","project":"myteam"},"spec":{"duration":"1h","panels":{"n":{"kind":"Panel","spec":{"display":{"name":"Notes"},"plugin":{"kind":"Markdown","spec":{"text":"# My first dashboard"}}}}},"layouts":[{"kind":"Grid","spec":{"items":[{"x":0,"y":0,"width":24,"height":6,"content":{"$ref":"#/spec/panels/n"}}]}}]}}' \
  -o /dev/null -w 'create dashboard: %{http_code}\n' curl -s -u admin:$PW http://127.0.0.1/api/v1/projects/myteam/dashboards/first | jq '.metadata.name'

Both create calls return 200, and the dashboard reads back as "first".

Perses ships percli, its command-line client, so you can manage dashboards as code and wire them into CI. Log in to your instance through the password gate, then apply resources from files:

/opt/perses/percli login http://admin:<PERSES_PASSWORD>@127.0.0.1 /opt/perses/percli apply -f my-dashboard.json /opt/perses/percli get dashboards --project demo

A Perses dashboard is a plain declarative document. Keep it in Git, validate it in CI and apply it on merge. This is the core of the dashboards-as-code workflow.

To visualize live data, add a datasource to a project, for example a Prometheus endpoint. Use the project's Datasources tab in the UI, or add it as a resource file. A project-scoped Prometheus datasource looks like this:

kind: Datasource metadata: name: prometheus project: demo spec: default: true plugin: kind: PrometheusDatasource spec: directUrl: http://your-prometheus:9090

Once a datasource exists, add a TimeSeriesChart, StatChart or GaugeChart panel to a dashboard and query it. The panel plugins for metrics, traces, logs and profiles all ship in the image.

• Perses server binary: /opt/perses/perses
• percli client: /opt/perses/percli
• Config file: /etc/perses/config.yaml
• File database (projects and dashboards): /opt/perses/data
• Bundled plugin archives: /opt/perses/plugins-archive
• systemd unit: /etc/systemd/system/perses.service
• First-boot script: /usr/local/sbin/perses-firstboot.sh
• Per-VM credentials note: /root/perses-credentials.txt (mode 0600)
• nginx Basic Auth file: /etc/nginx/.perses.htpasswd (per-VM bcrypt)

Confirm that the files exist and that the health endpoint responds:

ls -1 /opt/perses/perses /opt/perses/percli /etc/perses/config.yaml /opt/perses/data curl -sI http://127.0.0.1/healthz | head -1

Restart the service and read its recent log lines with:

sudo systemctl restart perses.service
sudo journalctl -u perses.service --no-pager -n 15

Perses is a single binary with a local file database, so it restarts in a second or two. The service is hardened with NoNewPrivileges, ProtectSystem=full and ProtectHome, and it has write access to its own directory only.

For production, terminate TLS at nginx. Point a DNS record at the VM, then use the packaged nginx with a certificate from Let's Encrypt:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

certbot installs the certificate, rewrites the nginx server block to listen on 443 and sets up automatic renewal. Keep the Basic Auth gate in place so the UI stays private over HTTPS.

The password lives in the nginx Basic Auth file. To set a new one, regenerate the entry with htpasswd (bcrypt), then reload nginx:

sudo htpasswd -B /etc/nginx/.perses.htpasswd admin
sudo systemctl reload nginx

Update /root/perses-credentials.txt if you want the note to reflect the new value. The password is stored only on this VM.

• Restrict the NSG so ports 80 and 22 reach only trusted networks.
• Terminate TLS at nginx (Step 16) so the UI and API travel encrypted.
• Keep Perses on loopback. It is served only through the nginx password gate, so do not bind it to a public interface.
• Rotate the password (Step 17) and store it in your secrets manager.
• Back up /opt/perses/data to Azure Blob so your projects and dashboards survive a rebuild.
• Patch the OS monthly with sudo apt-get update && sudo apt-get upgrade. Unattended security upgrades are already enabled.

Perses is licensed under the Apache License 2.0, with no per-CPU or per-user fee. SecureAnyCloud provides commercial support separately.

• Email: sales@secureanycloud.com
• Website: secureanycloud.com
• Support hours: 24/7, 24h response SLA

Deploy on Azure

Launch Perses on Ubuntu 24.04 with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7. sales@secureanycloud.com

Deploy on Azure

Launch Perses on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Subscribe to the SecureAnyCloud Perses listing in AWS Marketplace and launch an instance. Pick the m5.large size and choose your VPC and subnet. Attach a security group that allows inbound TCP 22 and TCP 80 from your trusted CIDR.

Connect to the instance as ubuntu:

ssh ubuntu@<public-ip>

Confirm that both the Perses server and the nginx reverse proxy are active. Perses is a single Go binary and starts in a second or two.

sudo systemctl is-active perses nginx

active active

nginx serves a static, unauthenticated health endpoint. Point an Application Load Balancer target group or an external uptime check at it, so probes never need the instance password.

curl -s -o /dev/null -w 'healthz HTTP %{http_code}\n' -m 10 http://127.0.0.1/healthz

healthz HTTP 200

Everything except /healthz sits behind the per-instance Basic Auth gate, so an unauthenticated request to the API must be rejected.

curl -s -o /dev/null -w 'unauthenticated API HTTP %{http_code}\n' -m 10 http://127.0.0.1/api/v1/projects

unauthenticated API HTTP 401

Then confirm the isolation. Perses itself listens only on loopback, and nginx is the only process bound to a public address.

sudo ss -tlnp | grep -E ':8080|:80 ' | awk '{print $1, $4, $6}'

LISTEN 0.0.0.0:80 users:(("nginx",pid=2223,fd=5),("nginx",pid=2222,fd=5),("nginx",pid=2221,fd=5)) LISTEN 127.0.0.1:8080 users:(("perses",pid=2214,fd=3)) LISTEN [::]:80 users:(("nginx",pid=2223,fd=6),("nginx",pid=2222,fd=6),("nginx",pid=2221,fd=6))

The loopback binding 127.0.0.1:8080 means the Perses API cannot be reached from the network except through the authenticated proxy.

The first-boot service generated this instance's web password and wrote the credentials file. Read the file now, and keep the terminal open while you sign in.

sudo cat /root/perses-credentials.txt

Note PERSES_URL, PERSES_USERNAME (always admin) and PERSES_PASSWORD. These values are unique to this instance and exist nowhere in the image. They are generated on the first boot of every instance you launch.

To confirm that the first boot ran cleanly, check the service log:

sudo journalctl -u perses-firstboot.service --no-pager -o cat | tail -3

Starting perses-firstboot.service - sac Perses first-boot (per-instance Basic Auth password + encryption key + URL/MOTD)... [2026-07-25T15:10:40+0000] perses-firstboot: First-boot prep complete; systemd will start perses + nginx. UI at http://13.221.114.30/ Finished perses-firstboot.service - sac Perses first-boot (per-instance Basic Auth password + encryption key + URL/MOTD).

Browse to http://<public-ip>/. Your browser prompts for a username and password, which shows the platform is not open to the internet. Enter admin and the PERSES_PASSWORD value from the credentials file.

The home view lists your projects. The seeded demo project is already there with one dashboard, so the interface is populated on a fresh launch.

Click into DEMO and open the Welcome dashboard. It uses Markdown panels, which render standalone with no datasource attached, so the dashboard is useful before you connect anything to it.

The project view lists that project's dashboards with creation and update times. It also has project-scoped tabs for Variables, Datasources and Secrets. Use them to add the Prometheus, Tempo, Loki or Pyroscope endpoint your dashboards will query.

The same REST API drives the interface, the CLI and any automation you write. Read the projects and dashboards back with the per-instance password.

PASS=$(sudo grep '^PERSES_PASSWORD=' /root/perses-credentials.txt | cut -d= -f2-)
curl -s -u "admin:${PASS}" -m 15 http://127.0.0.1/api/v1/projects | python3 -c "import sys,json;d=json.load(sys.stdin);print('projects:',len(d));[print(' -',p['metadata']['name']) for p in d]"

projects: 1 - demo

PASS=$(sudo grep '^PERSES_PASSWORD=' /root/perses-credentials.txt | cut -d= -f2-)
curl -s -u "admin:${PASS}" -m 15 http://127.0.0.1/api/v1/projects/demo/dashboards | python3 -c "import sys,json;d=json.load(sys.stdin);print('dashboards in demo:',len(d));[print(' -',x['metadata']['name'],'|',x['spec'].get('display',{}).get('name','')) for x in d]"

dashboards in demo: 1 - welcome | Welcome

Perses scopes dashboards, datasources and secrets by project, typically one per team or per system. Create a project over the API. The Create Project button in the interface does the same thing.

PASS=$(sudo grep '^PERSES_PASSWORD=' /root/perses-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'create project HTTP %{http_code}\n' -m 15 -u "admin:${PASS}" \
  -H 'Content-Type: application/json' -X POST http://127.0.0.1/api/v1/projects \
  -d '{"kind":"Project","metadata":{"name":"my-team"}}'
curl -s -u "admin:${PASS}" -m 15 http://127.0.0.1/api/v1/projects | python3 -c "import sys,json;d=json.load(sys.stdin);print('projects now:',[p['metadata']['name'] for p in d])"
curl -s -o /dev/null -w 'cleanup delete HTTP %{http_code}\n' -m 15 -u "admin:${PASS}" -X DELETE http://127.0.0.1/api/v1/projects/my-team

create project HTTP 200 projects now: ['demo', 'my-team'] cleanup delete HTTP 204

The last command removes the throwaway project again. Omit it when you create a project you intend to keep.

The bundled percli command-line tool powers the dashboards-as-code workflow. Dashboard definitions live in your Git repository, and the CLI applies them to a Perses instance from CI. Check the installed version:

/opt/perses/percli version

client: buildTime: "2026-03-12" version: 0.53.1 commit: 2b65a98ba3febd6342d5d99c1b498c6ff7ae08f2

From a workstation, log in to this instance and apply a dashboard definition from a file. The CLI takes the Basic Auth credentials in the URL, and the file is the same JSON the API accepts:

percli login http://admin:<password>@<public-ip> percli apply -f my-dashboard.json --project my-team

Keep those definitions in version control and run percli apply from your pipeline. Dashboard changes are then reviewed like any other change.

Open the Config view in the top navigation to see the running server configuration and the installed plugin set. Note three settings: enable_auth: false (the nginx gate is the single credential surface), the file-based store at /opt/perses/data, and the at-rest encryption_key, shown only as <secret>.

You can also confirm the plugin set over the API. All 24 bundled panel and query modules, including Markdown, TimeSeriesChart, StatChart and the Prometheus datasource, are extracted and loaded at startup.

PASS=$(sudo grep '^PERSES_PASSWORD=' /root/perses-credentials.txt | cut -d= -f2-)
curl -s -u "admin:${PASS}" -m 15 http://127.0.0.1/api/v1/plugins | python3 -c "import sys,json;d=json.load(sys.stdin);print('plugin modules loaded:',len(d))"

plugin modules loaded: 24

The image ships a diagnostic that checks the whole stack end to end. It covers the health endpoint, the authentication gate (unauthenticated and wrong-password requests are both rejected), the seeded demo resources, and a full create, read and delete round-trip through the proxy. Run it any time you want to confirm the instance is healthy.

PASS=$(sudo grep '^PERSES_PASSWORD=' /root/perses-credentials.txt | cut -d= -f2-) sudo /usr/local/sbin/perses-selftest.sh "$PASS"

OK perses gate + REST round-trip + demo resources verified

Perses queries your existing observability backends and does not store metrics itself. In the interface, open your project and go to the Datasources tab. Add a datasource that points at your Prometheus, Tempo, Loki or Pyroscope endpoint. Then create a dashboard with a TimeSeriesChart panel whose query targets it.

Keep two points in mind:

• Reachability. The datasource URL is resolved from this instance, so the security group and routing between this instance and your metrics backend must allow the connection.
• Secrets. Credentials for a datasource go in the project's Secrets tab. They are encrypted at rest with the per-instance encryption key generated at first boot, which is why that key never ships inside the image.

Work through this checklist before you expose Perses beyond a trusted network:

• TLS termination. Add a certificate and redirect port 80 to 443, either on an Application Load Balancer in front of the instance or on the instance itself. Basic Auth over plain HTTP sends the password in a reversible encoding, so terminate TLS before the instance is reachable over an untrusted network.
• Restrict the security group. Limit inbound TCP 80 and 22 to your office or VPN CIDR rather than leaving them open to the world.
• Rotate or add web users. The gate is a standard bcrypt htpasswd file. Add users with sudo htpasswd -B /etc/nginx/.perses.htpasswd <user> and reload nginx. Rotate the admin entry the same way, then update your records.
• Back up /opt/perses/data. That directory is the entire dashboard store: projects, dashboards, datasources and encrypted secrets. Snapshot the volume or copy the directory on a schedule.
• Protect the encryption key. /etc/perses/perses.env holds the at-rest key for datasource secrets. If you restore /opt/perses/data onto a different instance, carry that key across, or the stored secrets will not decrypt.
• Keep it patched. Unattended upgrades are enabled for OS packages. Perses itself is a pinned upstream release under /opt/perses, so review the upstream release notes before you replace the binary.