Volumes

Files a container writes are gone after the next deploy, unless they're on a volume.

A service with a volume stops its old container before the new one starts (two can't share the data), so its deploys have a gap of a few seconds; see Deployments.

A volume is for a database's files and other data a program keeps on disk. For files your app keeps for its users (uploads, exports, generated images), use a bucket instead: a service with a volume runs on one server, and one that keeps its files in a bucket can still scale out and move.

Add one

In the service's Volumes tab, give it a name, the path inside the container (e.g. data at /var/lib/postgresql/data) and its size. Volumes can also come from a docker-compose file or alf.toml.

Its size

A volume has the size you give it: 1 GB unless you say (a database's, its engine's). It's what the volume may hold, it's set aside for it on its server's disk, and it's what it's billed for, full or not: $0.10 per GB a month, so 10 GB is $1.

Its size is a ceiling it can't be written past, so one service filling up can't fill its server's disk and take its neighbours down with it. If it fills up, its service is stopped and the volume shows Full: make it bigger, or delete data from inside the container, and the service starts again.

Size under the volume changes it at once, without a deploy or a restart: bigger, as far as your plan allows (100 GB on Hobby) and its server has room, or smaller, down to what it holds. It's billed by its new size from then on. (A filesystem can't be made smaller while it's in use, so one made smaller is held to its new size by measuring it every half minute: the programs in it still see the bigger disk, and if it fills past the new size its service is stopped, as one that's full.)

For a big import, make room for it first: alf db restore does it by itself from the file's size, and the API takes room_for_gb (room for that much, and a quarter again).

Growing by itself

A volume can also grow by itself before it's full: once it's 80% full it's given half as much room again (enough to be at most 60% full after), live, with nothing restarted, and is billed by its new size. It's off unless you switch it on under Size (As it fills) or give it a limit (grow_up_to_gb in the API, grow_up_to in alf.toml). It grows:

You hear about it on the notification channels that follow A volume grew by itself, and once when it can't grow any further.

Good to know