# Installing it, and telling whether it works

## Install

The plugin updates itself from its release repository, but the **first**
install is manual, and on a copy older than 0.2.3 it has to be.

1. Download `nolimit-cache.zip` from the latest release at
   `https://gitea.nolimit.dk/kw/nolimit-cache-dist/releases`.
2. Plugins → Add New → Upload Plugin → Activate.
3. After that, updates appear in the normal update row.

> **Below 0.2.3, do not trust the update row.** Versions before 0.2.3 could
> offer another Nolimit plugin's zip as their own update. Upgrading *to*
> 0.2.3 or later has to be done by hand for that reason; after that the update
> row is safe.

## Activation writes two things outside the plugin folder

- `wp-content/advanced-cache.php` — the drop-in. Without it nothing is served
  from cache, however the settings look.
- `WP_CACHE` in `wp-config.php` — WordPress only loads the drop-in when this
  constant is true.

If `wp-config.php` is not writable, the plugin says so on its own screen
rather than failing quietly. That is the single most common reason for "it is
switched on and nothing is cached".

## The settings that are a decision

Everything else has a defensible default. These four do not:

| Setting | Why it needs a decision |
|---|---|
| **Cache lifetime** | How stale a page may be. A shop with frequent price changes wants a short one; a mostly-static site can leave it long, because a change purges the affected pages anyway. |
| **Excluded URIs / cookies** | Anything that must never be served from a shared copy. The WooCommerce basket, checkout and account pages are already excluded and cannot be un-excluded. |
| **Object cache (Redis)** | Off unless there is a Redis to point it at. It replaces `object-cache.php`, so it interacts with anything else that wants that file. |
| **CDN rewriting** | Only if assets are genuinely served from the other host. Wrong here means missing images rather than slow ones. |

## Images: WebP and AVIF

**Nolimit → Cache → Images** writes WebP (and, if the server can, AVIF) copies
next to your JPEG and PNG files and offers them to browsers that understand
them. The originals are never touched, so switching it off, or deleting the
copies, leaves the site exactly as it was.

- Conversion runs in the background; the screen shows how many of the library
  are done and how much space was saved.
- If an image changes size or position after switching on, pick the second
  delivery option on the same screen. A few themes style images with selectors
  that the extra `<picture>` element breaks.

## How to tell it is working

Do not read the settings page for this. Read these, in order.

### 1. The hit ratio, on **Nolimit → Cache**

The dashboard shows a hit ratio over the last 7 days and a count of stored
pages. **Two numbers produced by different routes**: stored pages are counted
by walking the disk, the ratio comes from a counter the engine writes before
WordPress boots. If pages are stored and the ratio says nothing has been
measured, those two disagree and the dashboard will say so explicitly rather
than showing a bare zero.

That distinction exists because a zero can mean two things, a quiet site or a
broken counter, and the dashboard should never leave you guessing which.

### 2. The response headers

```
curl -sI https://example.test/ | grep -i x-nolimit
```

A served-from-cache response carries the plugin's header. A logged-in request
or one with a basket cookie should **not**.

### 3. The health report

**Nolimit → Cache → Health** runs each signal and says which failed and why —
the drop-in missing, the cache directory not writable, `WP_CACHE` unset, the
drop-in pointing at a different copy of the plugin. Each is measured by doing
the thing (writing a file, reading the config the engine reads), not by
calling `is_writable()` and believing it.

## Turning it off

Deactivating removes the drop-in. If a drop-in is ever left behind — a
half-finished delete, a file permission problem — a site can end up serving
from a cache no plugin is managing. `wp-content/advanced-cache.php` is safe to
delete by hand; WordPress treats its absence as "no page cache".