Skip to main content

Logo Versity S3 Gateway

About​

Versity S3 Gateway (versitygw) is an S3 compatible object storage server that stores buckets and objects as plain files and directories on the app's filesystem.

Admin credentials​

The initial root credentials are versitygw / changeme123. Change them after install.

Change the credentials by editing ROOT_ACCESS_KEY and ROOT_SECRET_KEY in /app/data/env.sh using the File manager:

env.sh
export ROOT_ACCESS_KEY=cloudron-a1b2c3d4e5f6a7b8
export ROOT_SECRET_KEY='Secr$et#pass'

Restart the app after making changes.

The root credentials are also the access key and secret key for S3 clients.

Domains​

Versity S3 Gateway uses two domains:

  • WebGUI domain - this domain is for accessing the bucket and object browser.

  • S3 API Domain - this endpoint responds to S3 API requests. This is the domain that you need to put into various configs and tools like s3cmd. Only the domain name is needed, no port should be added.

The locations can be changed in the Location section in the Cloudron dashboard.

S3 clients​

Use the S3 API domain as the endpoint and the root credentials (or the credentials of a user) to connect any S3 compatible client. The region is us-east-1.

Bash
aws configure --profile versity

aws s3 mb s3://my-bucket --endpoint-url https://s3-versitygw.example.com --profile versity
aws s3 ls --endpoint-url https://s3-versitygw.example.com --profile versity

rclone​

Use the Other S3 provider and set location_constraint to us-east-1:

rclone.conf
[versitygw]
type = s3
provider = Other
endpoint = https://s3-versitygw.example.com
location_constraint = us-east-1
access_key_id = versitygw
secret_access_key = changeme123
Bash
rclone mkdir versitygw:my-bucket
rclone copy ./photos versitygw:my-bucket/photos
rclone ls versitygw:my-bucket

Users​

Users are managed with the admin subcommand of the versitygw CLI. Run it from the Web terminal:

Bash
# create a user
/app/code/versitygw admin -a versitygw -s changeme123 -er https://s3-versitygw.example.com \
    create-user -a alice -s sTr0ngPassword -r user

# list users
/app/code/versitygw admin -a versitygw -s changeme123 -er https://s3-versitygw.example.com list-users

# delete a user
/app/code/versitygw admin -a versitygw -s changeme123 -er https://s3-versitygw.example.com \
    delete-user -a alice

-a and -s after admin are the root credentials, -er is the S3 API domain. The role (-r) is one of user, userplus or admin. User accounts are stored in /app/data/iam/users.json.

Storage layout​

Buckets are stored as directories on the app's filesystem:

  • /app/data/buckets - buckets and objects
  • /app/data/versions - previous object versions
  • /app/data/iam - user accounts

The locations can be changed by uncommenting and editing BUCKETS_DIR, VERSIONS_DIR and IAM_DIR in /app/data/env.sh. Use this to store buckets on a Volume:

env.sh
export BUCKETS_DIR="/media/objectstore/buckets"

Restart the app after making changes.

Since objects are plain files, existing directory trees can be served as buckets by pointing BUCKETS_DIR at them.