Vinyl Cache on Ubuntu 24.04 on Azure User Guide

Overview

This image runs Vinyl Cache, a high performance HTTP reverse proxy and caching accelerator. Vinyl Cache sits in front of your web origin and serves cached responses from memory at very high speed, cutting origin load and latency. Caching behaviour is controlled with a flexible configuration language, so you decide exactly what to cache, for how long, and how requests and responses are transformed. The service is fully configured and security hardened, so you can put a cache in front of your site within minutes of launch.

The image ships ready to use. Vinyl Cache listens on port 80, the public accelerator port, and is preconfigured to cache a bundled demo origin that runs on the loopback address, so the appliance caches out of the box and you can prove it works before you change anything. When you are ready, a single command points the cache at your own web origin.

The image is secure by default. The Vinyl Cache management interface is bound to the loopback address only and is protected by a per VM secret that is generated fresh on the first boot of every deployed VM, never a baked in default. Only the cache port (80) and SSH are reachable from the network; the management interface and the bundled demo origin are confined to the loopback address. On the first boot of every VM, a one shot service records the cache details, the server's private IP and the exact command to point the cache at your origin, in a root only information file.

What is included:

• Vinyl Cache 9.0.1 built from the official source release, running as the vinyl-cache system service on port 80
• Secure by default: the management interface binds to 127.0.0.1:6082 only, protected by a per VM secret at /etc/vinyl/secret
• A bundled demo origin on 127.0.0.1:8080 so the cache works and can be proven the moment it boots
• An X-Cache: HIT / X-Cache: MISS response header so cache behaviour is directly observable
• vinylctl management tool in /usr/local/sbin (status, backend, reload, hitcheck)
• Per VM first boot initialisation writing cache details to /root/vinyl-cache-info.txt
• Clean open source built from the pinned upstream tarball, no third party binaries
• 24/7 cloudimg support

Prerequisites

Before you deploy this image you need:

• An active Microsoft Azure subscription where you can create virtual machines
• An SSH key pair for administrator access to the VM
• A virtual network and subnet in the target region
• A network security group (NSG) that allows inbound TCP 22 from your administrator network and inbound TCP 80 from the clients or CDN that will send traffic to the cache
• A reachable web origin (your application or web server) once you move past the bundled demo origin
• The Azure CLI installed locally if you plan to deploy from the command line

Standard_B2s (2 vCPU / 4 GiB RAM) is a balanced default; size the VM to the throughput and working set you expect. Vinyl Cache serves cached objects from memory, so more RAM means a larger cache.

Step 1: Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, and search the Marketplace for Vinyl Cache by cloudimg. Select the listing and choose Create.

On the Basics tab pick your subscription and resource group, a region, and a VM size (Standard_B2s or larger). Under Administrator account select SSH public key, set the username, and paste your public key. Under Inbound port rules allow SSH (22) for administration and HTTP (80) for the cache, scoped to the clients or CDN that will use it. Select Review + create, then Create. First boot initialisation completes within a few seconds of the VM reaching the Running state.

Step 2: Deploy from the Azure CLI

The following block creates a VM from the cloudimg Vinyl Cache image into an existing VNet and subnet. Replace the placeholders with your own values.

az vm create \
  --resource-group <your-rg> \
  --name vinyl-cache \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

# Allow the cache port from the clients / CDN that will use it.
az vm open-port --resource-group <your-rg> --name vinyl-cache --port 80 --priority 1010

Step 3: Connect as the Administrator over SSH

Connect to the VM with SSH as the administrator user you set at deploy time (azureuser by default on Ubuntu). The administrator account is SSH key only.

ssh azureuser@<vm-public-ip>

Step 4: Confirm the Cache is Running

Vinyl Cache starts automatically on boot. Confirm the cache service and the bundled demo origin are active, and inspect the listen sockets:

systemctl is-active vinyl-cache.service vinyl-origin.service
sudo ss -tlnp | grep -E ':(80|6082|8080)'

The cache listens on 0.0.0.0:80 (the public accelerator port), while the management interface (127.0.0.1:6082) and the bundled demo origin (127.0.0.1:8080) are bound to the loopback address only. Expected output:

active
active
LISTEN 0      1024   127.0.0.1:6082   0.0.0.0:*  users:(("vinyld",...))
LISTEN 0      1024   127.0.0.1:8080   0.0.0.0:*  users:(("nginx",...))
LISTEN 0      10     0.0.0.0:80       0.0.0.0:*  users:(("vinyld",...))
LISTEN 0      10        [::]:80          [::]:*  users:(("vinyld",...))

Step 5: Prove the Cache is Working

The image ships pointed at a bundled demo origin, so you can prove caching immediately. Make the same request twice through the cache and watch the X-Cache response header: the first uncached request is a MISS, and every subsequent request is served from cache as a HIT. The X-Cache-Hits counter shows how many times the object has been served from cache.

curl -s -D - -o /dev/null http://127.0.0.1/ | grep -i '^x-cache'
curl -s -D - -o /dev/null http://127.0.0.1/ | grep -i '^x-cache'
sudo vinylctl hitcheck

Expected output (the second and later requests are cache hits):

X-Cache: HIT
X-Cache-Hits: 5
X-Cache: HIT
X-Cache-Hits: 6
X-Cache: HIT
X-Cache-Hits: 7

You can also read the cache counters directly. MAIN.cache_hit climbs with every request served from cache:

sudo vinylstat -n /run/vinyl -1 -f MAIN.cache_hit -f MAIN.cache_miss

Step 6: Point the Cache at Your Own Origin

The cache ships pointed at the bundled demo origin. Point it at your own web origin with the vinylctl tool. Use your own origin's host and port; the value below is only an example:

sudo vinylctl backend 10.1.0.10:8080     # your origin host:port
sudo vinylctl status

vinylctl backend rewrites the backend definition in /etc/vinyl/default.vcl and reloads the cache with no downtime. Review the current backend, the listen sockets and the cache hit counter at any time:

sudo vinylctl status

The Backend origin block shows where the cache forwards uncached requests, and the Cache hit counter shows how much traffic is being served from cache.

Step 7: Secure by Default — the Management Interface

Read the first boot information file and the cache summary at any time. The file records the server's private IP and the exact command to point the cache at your origin:

sudo cat /root/vinyl-cache-info.txt
sudo stat -c '%a %U:%G' /etc/vinyl/secret

The management interface (127.0.0.1:6082) is bound to the loopback address only and is authenticated by a per VM secret at /etc/vinyl/secret, mode 600 root:root. That secret is generated fresh on the first boot of every VM, never shipped in the image, so no two deployments share a management credential and there is no baked in default to leak. Only the cache port (80) and SSH are reachable from the network; the management interface and the demo origin never leave the loopback address.

echo -n 'public TCP ports: '; sudo ss -tlnH | awk '{print $4}' | grep -vE '^(127\.|\[::1\])' | awk -F: '{print $NF}' | sort -un | paste -sd' ' -

The only publicly bound ports are 22 (SSH) and 80 (the cache). The management interface is never exposed.

Step 8: Customising the Cache with VCL

Vinyl Cache caching policy lives in /etc/vinyl/default.vcl. The shipped policy caches GET and HEAD responses, strips client cookies on the demo path, and adds the X-Cache header so you can observe cache behaviour. Edit the file to tune your caching policy — which paths to cache, time to live, header handling — then reload with no downtime:

sudo nano /etc/vinyl/default.vcl
sudo vinylctl reload

vinylctl reload recompiles the configuration and activates it with no dropped connections. If the configuration has a syntax error the reload is refused and the running cache keeps serving, so a bad edit never takes the cache down.

Step 9: Managing the Cache

The vinylctl tool is the primary interface to the cache:

The cache service is a standard systemd unit, so you can also use systemctl to manage it:

sudo systemctl status vinyl-cache.service
sudo systemctl restart vinyl-cache.service

Step 10: Hardening Notes

The image is hardened out of the box: the management interface binds to the loopback address only and is protected by a per VM secret, only the cache port and SSH are public, and the bundled demo origin is confined to the loopback address. Keep it locked down in production: scope the NSG rule for TCP 80 to the clients or CDN that need the cache, never expose the management interface, keep your VCL caching policy scoped to the paths you intend to cache, and keep the OS patched (sudo apt update && sudo apt upgrade). Put TLS termination (a load balancer or a TLS front end) in front of the cache for HTTPS traffic, and consult the Vinyl Cache documentation for the full configuration language reference.

Support

This image is backed by 24/7 cloudimg support. Contact us by email and chat for help with Vinyl Cache configuration, caching policy, pointing the cache at your origin, cache invalidation, and reverse proxy cache architecture on Azure.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.