Resources
A project holds several resources - the app, volumes, databases and caches - and attaching one to the app turns it into config vars.
A project is a namespace with resources in it: the app, volumes, buckets, PostgreSQL databases and Redis-compatible stores. shpyrd projects info and the project page list them all with their status and what uses them.
Resources: App hello-docker Running https://acme-hello-docker.shpyrd.app Volume data Bound 1Gi single-instance, mounted by hello-docker/webEvery resource is a Kubernetes object in the project's namespace, so on a cluster you run yourself nothing is hidden from the tools you already use. The namespace is p-<id> (older projects: app-<slug>), labelled shpyrd.io/project=<slug>: kubectl get apps,volumes.shpyrd.io -A -l shpyrd.io/project=hello-docker.
Volumes
A volume is a persistent disk of the project, backed by a PersistentVolumeClaim that the Volume resource owns. Deploys, scaling and crashes never touch it; only shpyrd volumes delete and the project's destruction remove it.
shpyrd volumes create data --size 5Gi # single-instance, the defaultshpyrd volumes create assets --size 20Gi --shared # shared by several instances and processesshpyrd volumes listshpyrd volumes delete data --yesMount it from shpyrd.yaml and deploy:
processes: web: volumes: - name: data path: /dataWhere the bytes live
On shpyrd cloud and on the Oracle Cloud and AWS profiles, a volume is a provider block volume (oci-bv, gp3): its disk starts at the provider's minimum (50 GB on Oracle Cloud; a smaller volume keeps the size you asked for on a disk of the minimum, and the answer and shpyrd volumes list say so), it can grow, it has nightly snapshots, and it follows its process to another node, so a node can be drained or lost without losing data. Databases and persistent stores keep their data the same way.
Volumes count against the workspace's block storage ceiling by the capacity they claim, with the disks of dedicated databases (once per instance) and durable stores. A volume that would pass it is refused with the numbers ("This would bring the workspace to 150 GB of 100 GB."); so is one that would pass the project's own cap, when the workspace set one. A workspace whose plan includes no disks (the free workspace) is refused a new volume in words ("Disks are not included in the free workspace; use a bucket for files, or upgrade.") and keeps the volumes it has, which may still grow within the ceiling. The dashboard's volume dialog says what may still be added before the request. A growth on a storage class that cannot grow disks is refused at once, and shpyrd volumes list and the resources page say where a growth stands: requested, pending while the provider grows the disk, completed, or failed with the reason.
On the local profile (a kind cluster on your machine) volumes live on the node's own disk (the shpyrd-local class): no minimum, no resize, no snapshots, and the processes that mount one run on that node. Volumes made on a cloud profile before it moved to block storage are still on the node's disk; they keep their class until a cluster admin migrates them, and the platform keeps the autoscaler from removing a node that holds such data.
Backups protect the bytes either way: a database's own backups, the nightly snapshots of block volumes, and the project archive a cluster admin exports from the console (a project's volumes' files and its databases, in one portable file).
Single-instance and shared volumes
shpyrd enforces who can mount a disk, so you cannot end up with a rollout that waits forever or a corrupted database.
| Single-instance (default) | Shared (--shared) | |
|---|---|---|
| Who mounts it | one process type, running one instance | any number of instances and process types |
| Rollouts | stop, release the disk, start (a few seconds of downtime per deploy, no data risk) | rolling, as usual |
| Good for | SQLite, uploads, caches, tool state | assets shared by several instances |
| Not for | anything needing more than one instance | SQLite and other file-locking databases |
The rules are explained where they bite: shpyrd scale web=3 on a process with a single-instance volume answers web mounts single-instance volume "data" and can run 1 instance (a shared volume allows more), mounting one single-instance volume from two process types is refused, and the dashboard pins the instance count to one. For a database, use the Postgres resource rather than SQLite on a shared volume.
Size and status
shpyrd volumes list shows the size, the mode, the status (Pending: created; the disk is provisioned when a process mounts it, then Bound, or Failed with the reason) and what mounts it. A block volume grows with shpyrd volumes resize (never below what it has; a volume under the provider minimum can be set to anything from its size up, and the disk grows once the size passes the minimum). A volume on the node's disk shares that disk's space and cannot be resized: shpyrd volumes resize explains that you grow the node's disk or move the project to a larger node. The access mode and storage class cannot change after creation.
Any image user can write to a mounted volume: the platform hands the disk to a group every container in the instance belongs to, so a Dockerfile USER or a buildpack's non-root user needs no chown step.
Self-hosted: on the local profile the node is the kind container, so shpyrd cluster destroy deletes the bytes along with everything else.
Snapshots
Block volumes have snapshots where the profile supports them (Oracle Cloud and AWS); volumes on the node's disk have none: shpyrd volumes snapshot refuses them and points to the project's backups.
shpyrd volumes snapshot data --name before-migration # a point-in-time copy of the diskshpyrd volumes snapshots data # list them, newest firstshpyrd volumes restore data --from before-migration --to data-copy # into a new volumeshpyrd volumes restore data --from before-migration --yes # in placeshpyrd volumes snapshot rm data before-migration --yesRestoring into a new volume is the safe path: the copy is created from the snapshot (at least the snapshot's size) and you mount it like any other volume. Restoring in place replaces what is on the volume now: the instances mounting it stop (stopped while volume data is restored), the disk is swapped for one created from the snapshot, and they start again as soon as it is ready; take a snapshot first if you may want the current contents back. Neither creates a release; both appear in the activity feed. The project's Resources page offers the same from a Snapshots button on each volume.
Snapshots are taken at the block level and are crash-consistent: before taking one, shpyrd runs sync in the instances mounting the volume, so what the application had written is in the copy; a database is still better served by its own backups. An operator can also snapshot every remaining provider disk at once with shpyrd-ctl cluster snapshots (Platform backups).
Buckets
A bucket holds an app's files: uploads, images, exports, anything several instances write and read. It is S3: every SDK, every tool that speaks S3, reaches it with a key that opens this bucket and nothing else. A bucket needs the object-storage extension, which shpyrd cloud has.
shpyrd buckets create uploads --project shop # up to the plan's cap per bucketshpyrd buckets create uploads --project shop --size 5Gi # a cap of its own, within the planshpyrd attach uploads --project shop --prefix AWS # the names the SDKs read, no codeshpyrd buckets list --project shopshpyrd buckets rotate uploads --project shop # a new key; the app restarts with itAttached, a bucket puts six variables in the app, under the prefix of the binding (BUCKET by default): BUCKET_ACCESS_KEY_ID, BUCKET_SECRET_ACCESS_KEY, BUCKET_ENDPOINT_URL, BUCKET_REGION, BUCKET_BUCKET (the bucket's name in S3) and BUCKET_URL (s3://<bucket>). With --prefix AWS they become AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL, AWS_REGION and AWS_BUCKET, the names the AWS SDKs pick up on their own; the bucket is then AWS_BUCKET. Addressing is path style (<endpoint>/<bucket>/<key>), which every SDK has a setting for. The region is us-east-1: a signing scope, not a place; on shpyrd cloud the data lives in Oracle Cloud's Ashburn region.
// Node, @aws-sdk/client-s3, attached with --prefix AWSimport { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";const s3 = new S3Client({ endpoint: process.env.AWS_ENDPOINT_URL, region: process.env.AWS_REGION, forcePathStyle: true });await s3.send(new PutObjectCommand({ Bucket: process.env.AWS_BUCKET, Key: "avatars/42.png", Body: file }));# Python, boto3, attached with --prefix AWSimport os, boto3s3 = boto3.client("s3", endpoint_url=os.environ["AWS_ENDPOINT_URL"], config=boto3.session.Config(s3={"addressing_style": "path"}))s3.upload_fileobj(file, os.environ["AWS_BUCKET"], "avatars/42.png")// Go, aws-sdk-go-v2, attached with --prefix AWScfg, _ := config.LoadDefaultConfig(ctx)client := s3.NewFromConfig(cfg, func(o *s3.Options) { o.BaseEndpoint = aws.String(os.Getenv("AWS_ENDPOINT_URL")); o.UsePathStyle = true })_, err := client.PutObject(ctx, &s3.PutObjectInput{Bucket: aws.String(os.Getenv("AWS_BUCKET")), Key: aws.String("avatars/42.png"), Body: file})# Rails, Active Storage (config/storage.yml), attached with --prefix AWSshpyrd: service: S3 access_key_id: <%= ENV["AWS_ACCESS_KEY_ID"] %> secret_access_key: <%= ENV["AWS_SECRET_ACCESS_KEY"] %> endpoint: <%= ENV["AWS_ENDPOINT_URL"] %> region: <%= ENV["AWS_REGION"] %> bucket: <%= ENV["AWS_BUCKET"] %> force_path_style: trueWhat a bucket holds
Every bucket has a cap, the plan's per bucket unless you ask for less (1 GB on the free workspace): an upload that would pass it is refused with the numbers ("This bucket holds up to 1 GB; this upload would bring it to 1.2 GB."), and what you delete is room again at once. Buckets count against the workspace's plan twice, by number and by their caps together; a bucket past either is refused in words before it is made, and the dashboard's bucket dialog says what the plan allows. The resources page shows each bucket's use against its cap. A bucket's objects are metered by the gigabyte-hour and billed with the workspace; requests are not itemised. Overwritten and deleted objects are kept by the platform for seven days, so a mistake has a week of undo through support.
From a browser
On shpyrd cloud a bucket is also reachable from outside the cluster, for a browser to upload and download without the app in the middle: the app signs an address for one object and one method (a presigned PUT or GET, every SDK makes them) with a client pointed at BUCKET_PUBLIC_ENDPOINT_URL, the same bucket through the platform's public door, and hands it to the page. A browser only follows such an address when the bucket allows its origin: set the bucket's CORS once from the app (PutBucketCors, with the SDK) naming the origins and methods it may use. A bucket made with --public lets anyone read an object by its address, without a key; listing and writing still need the key. Requests to one bucket are limited to a thousand a second; past that the gateway answers SlowDown, which the SDKs retry with backoff.
What a bucket is not
Not a disk: an app cannot open a file on it, there is no rename and no locking. SQLite, a tool's state or anything that needs a file system goes on a volume. Not versioned: a bucket keeps one version of each object; the platform's own undo is the week above.
A bucket travels with the project's archive by reference: the archive names it, and a restore on the same platform finds the files where they are; tick the archive's option to carry the files too (up to 5 GB together), for a backup before destroying the project or a move to another platform.
Attaching resources
Attaching a resource to the app injects its connection details as config vars, Heroku style: a Postgres named db provides DATABASE_URL, DATABASE_HOST, ...; a bucket named uploads provides BUCKET_ACCESS_KEY_ID, BUCKET_ENDPOINT_URL, ... The variables are read-only on the project's Config page and in shpyrd secrets list, shown with the resource that provides them, and take precedence over a config var of the same name. Attaching or detaching is a config release ("Attach Postgres db") that rollback undoes like any other. See Databases and caches for shpyrd pg, shpyrd redis, shpyrd attach and shpyrd detach.