Switch target¶

pless knows one kind of destination: something reachable over SSH. Moving between a Raspberry Pi, a VM on your hypervisor and a cloud server is a configuration change, not a different tool — and not even a change of kind.

[host]
address = "archive.local"
user = "admin"

pless audit against a VM runs exactly the checks it runs against your Pi, because to the tool they are the same thing.

Rehearse before you touch real hardware¶

This is the most useful thing a second target gives you. Before running something consequential on the machine holding your documents, run it on a VM that costs nothing to destroy.

[vm]
backend = "lima"     # Debian 13, SSH bootstrap — like a Pi

pless vm create      # also points [host] at the new VM
pless bootstrap
pless storage init --confirm     # throwaway passphrase
pless deploy paperless
pless audit

Try the upgrade, the storage migration, the configuration change. Break it, destroy it, start over:

pless vm destroy --confirm

Then point [host] at the real machine and do it again, knowing what the output should look like.

Match the backend to the destination¶

The two VM backends rehearse different production paths:

Heading for a Pi? Use Lima. It exercises the same bootstrap path and the same Debian package names — which matters more than it sounds, because the Docker packages genuinely differ between the distributions. Debian ships Compose v2 as docker-compose and splits the client into docker-cli; Ubuntu ships it as docker-compose-v2 with the client included. pless handles both, and the VM is where you find out if that handling ever breaks.

Run several targets at once¶

Keep separate configuration files:

pless.toml          # your Pi
pless.vm.toml       # scratch VM

pless walks up from your working directory looking for pless.toml, the way git finds its repository root. The simplest way to keep two live is separate directories, each with its own config and .env.

Note that pless vm create writes [host] for you, and refuses to repoint it at a different machine without --force — so it cannot quietly steer a config away from a machine holding documents.

Moving an archive between targets¶

There is no migration command yet — it needs the backup and restore machinery that has not been built. The manual route works today:

1. Copy the data out, following Copy it out by hand.
2. Set up the new target completely: bootstrap, storage init, deploy.
3. Stop the stack there: pless lock.
4. Restore the copy into /opt/paperless on the new target.
5. pless unlock, then verify with pless paperless health and a search in the web interface.

Use the same passphrase on both if you want the option of moving the encrypted volume itself rather than its contents.

Keep the old target intact until the new one has proven itself. Documents present, search working, a few files opened and read. Only then reclaim the hardware.

Cost, briefly¶

The VM is a rehearsal space, not a home. It lives on a laptop that sleeps, travels, and gets reinstalled.