Store files in a bucket

Create a bucket, get its address and keys, and use it from any S3 client.

Create a bucket

  1. In the console, press ⌘K and choose Workspace › New bucket. Type a name of 3 to 63 characters: lowercase Latin letters, digits and hyphens, starting and ending with a letter or a digit.

    The name is the bucket's address, and it can't change later.

  2. Pick the site the bucket lives in and choose Create.

    The objects stay at the site picked here, and it can't change later. No two buckets share a name, at any site.

The bucket belongs to your workspace, not to a project, and it has no deploys. When your plan has no room for another bucket, the console says The plan has no room for this bucket and creates nothing; each plan's room is in limits and prices. Stored files bill by the GB each month, and objects unread for 30 days bill at the cold rate, as billing explains.

From the CLI, ghaym cloud buckets create --name my-bucket --site amman-1 creates a bucket, and ghaym cloud buckets credentials get my-bucket --show prints its keys once it's ready.

Not available

File versions, object lock, a second copy of a bucket, or a custom domain on a bucket.

Use it from code

Open the bucket under Object Storage. Endpoints lists three values:

  • Public endpoint: https://my-bucket.s3.jo.cloud.ghaym.me, for presigning and public reads.
  • In-project endpoint: http://s3, from inside a project's network only.
  • Signing region: jo, the country code an S3 client signs with.

Under Keys, choose Show the keys to read the access key ID and the secret access key. Any S3 client takes these values; there's no Ghaym library to install. To hand them to a service as variables, connect the bucket to it. A bucket connects only to a service in its own site.

From a service, use the in-project endpoint with path-style addressing:

js
import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.S3_REGION,
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  },
});

await s3.send(
  new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: "reports/june.pdf", Body: bytes }),
);
python
import os

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    region_name=os.environ["S3_REGION"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"],
    config=Config(s3={"addressing_style": "path"}),
)

s3.upload_file("june.pdf", os.environ["S3_BUCKET"], "reports/june.pdf")

From your laptop, a CI job or a server outside Ghaym, give the client https://s3.jo.cloud.ghaym.me and the region jo, and leave path-style off: the client puts the bucket's name in front, which makes the public endpoint.

js
const s3 = new S3Client({
  endpoint: "https://s3.jo.cloud.ghaym.me",
  region: "jo",
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  },
});

Make it public

Open the bucket, press ⌘K and choose Make the bucket public. Anyone will be able to read this bucket's objects by URL. Listing and writing still need a key. Public objects are served from the public endpoint.

To close it again, choose Make the bucket private: only a signed request will read this bucket's objects.

Rotate or delete it

To replace the key pair, open the bucket, press ⌘K and choose Rotate the keys. With no service connected, the current pair stops working at once. When services are connected, the current pair keeps working until they are redeployed, for a day at most. Any other client using it needs the new keys.

To delete the bucket, press ⌘K, choose Delete bucket and type the bucket's name to confirm. Deleting the bucket destroys its objects and its keys. Nothing is kept.