Deploying a VictoriaMetrics App

Introduction

VictoriaMetrics is a fast, cost-effective time-series database compatible with Prometheus and Graphite. This guide shows how to containerize the single-server edition with a Dockerfile, persist its data, and deploy it to Klutch.sh over HTTP for ingestion and querying.

Prerequisites

• GitHub repository containing your Dockerfile.
• Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM victoriametrics/victoria-metrics:latest

# Default HTTP/ingest/query port
ENV VM_PORT=8428
EXPOSE 8428

# Run with default flags; override via env and entrypoint as needed
CMD ["/victoria-metrics", "-storageDataPath=/victoria-metrics-data"]

Recommended environment variables / flags

• VM_PORT=8428 – internal port.
• VM_RETENTION_PERIOD=12 – retention in months (pass as -retentionPeriod flag if needed).
• VM_MAX_INSERT_RATE – throttle inserts if desired (-maxInsertRate).
• VM_SELF_SCRAPE_INTERVAL=0 – disable self-scrape if not needed.

Map these to flags in CMD or ENTRYPOINT, e.g., CMD ["/victoria-metrics","-storageDataPath=/victoria-metrics-data","-retentionPeriod=12"].

Persistence

VictoriaMetrics stores data locally:

• Mount path: /victoria-metrics-data
• Size: based on expected retention and ingestion rate

Networking

• Protocol: HTTP
• Internal port: 8428
• Users and agents reach https://example-app.klutch.sh while Klutch.sh routes to 8428 inside the container.

Health check (recommended)

curl -I http://localhost:8428/health

Deployment on Klutch.sh

1. Push your Dockerfile to GitHub.
2. In klutch.sh/app, create a new app and select GitHub as the source.
3. Klutch.sh automatically detects the Dockerfile in the repository root.
4. Select HTTP traffic and set the internal port to 8428.
5. Add environment variables or flags for retention and ingestion limits (VM_RETENTION_PERIOD, etc.).
6. Attach a persistent volume at /victoria-metrics-data sized for your retention and cardinality.
7. Deploy. Point your Prometheus remote_write or agents to https://example-app.klutch.sh/api/v1/write and use /api/v1/query for reads.

Verification

• Health endpoint:

  curl https://example-app.klutch.sh/health

• Sample query:

  curl "https://example-app.klutch.sh/api/v1/query?query=up"

Next steps

• Tune retention and insert rate flags to match your workload.
• Enable authentication at your ingress layer if needed.
• Schedule backups or snapshots from the /victoria-metrics-data volume.