Set up a Remote Repository¶

A remote repository lives in an S3-compatible object storage bucket, which is how a repository is shared between people and machines. This guide covers choosing a provider, creating the repository, and connecting a workspace to it. For a shorter linear walkthrough, see Getting Started; for a repository on your local disk instead, see Set up a Local Filesystem Repository.

FlexVault talks to the bucket directly using the S3 API, so any provider that exposes an S3-compatible endpoint works.

Choose a storage provider¶

The provider you pick affects cost and performance more than functionality. These four are good choices:

AWS S3 and Google Cloud Storage are the most widely used and are very reliable, but they charge for egress, which adds up when a team pulls large amounts of data. Cloudflare R2 removes egress fees and offers strong throughput, at the cost of higher latency. Tigris offers both strong throughput and low latency.

Whichever you choose, create a bucket and generate an access key ID and secret access key with read and write access to it before continuing.

How the endpoint is resolved¶

• AWS S3: pass --s3-region set to your bucket's region (for example us-east-1, eu-west-1, or ap-southeast-2) and FlexVault builds the endpoint from your s3:// URI automatically. Do not pass --s3-http-endpoint.
• Other providers: pass --s3-http-endpoint with the full URL pointing at where the repository should live. FlexVault uses this value exactly as given and does not append your bucket or repository path to it. Set --s3-region auto for Cloudflare R2 and Tigris; omit --s3-region for Google Cloud Storage.

Providers differ in where the bucket name goes. Tigris puts it in the hostname, while Cloudflare R2 and Google Cloud Storage put it in the path:

Anything you add after that base is an optional prefix, useful when you want to keep the repository under a specific path rather than at the root of the bucket. The examples below use a my-repo prefix so one bucket can hold more than one repository.

Credentials are supplied only through the --s3-* flags below. FlexVault does not read environment variables, AWS_* variables, or ~/.aws profiles.

Create the repository¶

Use fxv repo new to initialize the repository in your bucket. The --admin-username is required: it seeds the repository's first user, who is recorded as the initial administrator.

fxv repo new s3://my-bucket/my-repo \
  --admin-username alice --admin-email alice@example.com \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-region REGION

fxv repo new s3://my-bucket/my-repo `
  --admin-username alice --admin-email alice@example.com `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-region REGION

fxv repo new s3://my-bucket/my-repo \
  --admin-username alice --admin-email alice@example.com \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-http-endpoint https://ACCOUNT_ID.r2.cloudflarestorage.com/my-bucket/my-repo \
  --s3-region auto

fxv repo new s3://my-bucket/my-repo `
  --admin-username alice --admin-email alice@example.com `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-http-endpoint https://ACCOUNT_ID.r2.cloudflarestorage.com/my-bucket/my-repo `
  --s3-region auto

fxv repo new s3://my-bucket/my-repo \
  --admin-username alice --admin-email alice@example.com \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-http-endpoint https://my-bucket.t3.storage.dev/my-repo \
  --s3-region auto

fxv repo new s3://my-bucket/my-repo `
  --admin-username alice --admin-email alice@example.com `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-http-endpoint https://my-bucket.t3.storage.dev/my-repo `
  --s3-region auto

fxv repo new s3://my-bucket/my-repo \
  --admin-username alice --admin-email alice@example.com \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-http-endpoint https://storage.googleapis.com/my-bucket/my-repo

fxv repo new s3://my-bucket/my-repo `
  --admin-username alice --admin-email alice@example.com `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-http-endpoint https://storage.googleapis.com/my-bucket/my-repo

This writes the repository's metadata into the bucket. The bucket now holds a complete FlexVault repository that workspaces can connect to.

Create a workspace against it¶

A repository is where published history lives; you do your actual work in a workspace on your machine. Create one with fxv init, pointing it at the same s3:// URI and passing the same storage flags:

fxv init s3://my-bucket/my-repo --path ./my-workspace \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-region REGION

fxv init s3://my-bucket/my-repo --path ./my-workspace `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-region REGION

fxv init s3://my-bucket/my-repo --path ./my-workspace \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-http-endpoint https://ACCOUNT_ID.r2.cloudflarestorage.com/my-bucket/my-repo \
  --s3-region auto

fxv init s3://my-bucket/my-repo --path ./my-workspace `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-http-endpoint https://ACCOUNT_ID.r2.cloudflarestorage.com/my-bucket/my-repo `
  --s3-region auto

fxv init s3://my-bucket/my-repo --path ./my-workspace \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-http-endpoint https://my-bucket.t3.storage.dev/my-repo \
  --s3-region auto

fxv init s3://my-bucket/my-repo --path ./my-workspace `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-http-endpoint https://my-bucket.t3.storage.dev/my-repo `
  --s3-region auto

fxv init s3://my-bucket/my-repo --path ./my-workspace \
  --s3-access-key-id KEY_ID \
  --s3-secret-access-key SECRET_KEY \
  --s3-http-endpoint https://storage.googleapis.com/my-bucket/my-repo

fxv init s3://my-bucket/my-repo --path ./my-workspace `
  --s3-access-key-id KEY_ID `
  --s3-secret-access-key SECRET_KEY `
  --s3-http-endpoint https://storage.googleapis.com/my-bucket/my-repo

Next steps¶

The repository and workspace are ready. From here, add a user and make your first publish, then invite others to sync against the same URI. Getting Started walks through the rest.