Quickstart

Download Gateway

Download release binary

Download a release binary from Releases

or Build from source

This assumes you have a Go compiler installed

• Clone repo

git clone https://github.com/versity/versitygw.git

• Build project

cd versitygw
make

Run Gateway

Create backend directory if it doesn't already exist

Enabling versioning is optional, but included in the examples. The examples also show how to enable the optional web ui on port 8080.

mkdir /tmp/vgw /tmp/vers

Start Gateway

Set the root account credentials with the ROOT_ACCESS_KEY and ROOT_SECRET_KEY environment variables. These can alternatively be set with --access and --secret cli options.
Examples:

ROOT_ACCESS_KEY=myaccess ROOT_SECRET_KEY=mysecret ./versitygw --iam-dir /tmp/vgw --webui :8080 posix --versioning-dir /tmp/vers /tmp/vgw

versitygw --access myaccess --secret mysecret --iam-dir /tmp/vgw --webui :8080 posix --versioning-dir /tmp/vers /tmp/vgw

Test client interactions

Using aws cli

Set client credentials to root account.

export AWS_ACCESS_KEY_ID=myaccess
export AWS_SECRET_ACCESS_KEY=mysecret

Create a bucket. Replace 127.0.0.1 with server IP if gateway running on different host.

aws --endpoint-url http://127.0.0.1:7070 s3 mb s3://mybucket

Upload a file "localfile" to the S3 gateway calling it "/test/file" within the bucket we just created.

aws --endpoint-url http://127.0.0.1:7070 s3 cp localfile s3://mybucket/test/file

Test WebUI

Open a browser on http://127.0.0.1:8080 and login with acesskey/secretkey credentials (myaccess/mysecret).

Run the standalone IAM service

For identity policies, IAM roles, access key management and OIDC federation, run the standalone IAM service instead of --iam-dir. Global options come before the iam subcommand, --dir after it, and the storage directory must already exist — the service does not create it.

mkdir -p /tmp/versitygw-iam
versitygw --port 127.0.0.1:7071 --access myaccess --secret mysecret iam --dir /tmp/versitygw-iam --private-ports /tmp/vgw-iam.sock

Users are created with the standard AWS CLI against the service, not with versitygw admin:

aws --endpoint-url http://127.0.0.1:7071 iam create-user --user-name bob
aws --endpoint-url http://127.0.0.1:7071 iam create-access-key --user-name bob

--private-ports above is the private endpoint the S3 gateway talks to. Point a gateway at the same socket; a unix socket needs no certificates:

versitygw --access myaccess --secret mysecret --iam-standalone-endpoint /tmp/vgw-iam.sock posix /tmp/vgw

See Standalone IAM Service for what changes on the S3 data plane and Setup & Gateway Integration for the full configuration.