Skip to main content

Migrate from AWS S3

For most applications, switching from AWS S3 to Filebase is a two-line code change: update the endpoint and the region. This guide covers both the code switch and the data move.

Code change​

In every place you initialize an S3 client, change the endpoint and region:

AWS SDK for JavaScript v3
  import { S3Client } from '@aws-sdk/client-s3';

  const s3 = new S3Client({
+   endpoint: 'https://s3.filebase.io',
+   region: 'auto',
-   region: 'us-east-1',
    credentials: {
      accessKeyId: process.env.S3_KEY,
      secretAccessKey: process.env.S3_SECRET,
    },
  });
boto3 (Python)
  s3 = boto3.client(
      's3',
+     endpoint_url='https://s3.filebase.io',
+     region_name='auto',
-     region_name='us-east-1',
      aws_access_key_id=os.environ['S3_KEY'],
      aws_secret_access_key=os.environ['S3_SECRET'],
  )
AWS SDK for Go v2
  client := s3.New(s3.Options{
+   BaseEndpoint: aws.String("https://s3.filebase.io"),
+   Region:       "auto",
-   Region:       "us-east-1",
    Credentials:  creds,
  })

That's typically all the application code that needs to change.

What probably changes too​

  • Bucket name. Filebase bucket names are globally unique and likely already taken if you re-use the AWS bucket name verbatim. Pick a new name.
  • CDN. If you're using CloudFront in front of AWS S3 today, see if the built-in Filebase CDN replaces it. For most read-heavy public-asset workloads, it does.
  • IAM policies. Filebase doesn't have IAM. You manage access through bucket-level ACLs (public-read or private) and pre-signed URLs for delegated access.
  • Lifecycle and versioning rules. See the compatibility matrix for what carries over.

What doesn't change​

  • The S3 SDK and CLI you already use.
  • Your signing logic — SigV4 works identically.
  • Your operations: PutObject, GetObject, multipart upload, pre-signed URLs, CORS.
  • The XML response format, ETag semantics, error codes, and pagination tokens.
  • Wire-protocol observability — the Filebase API logs the same RequestIds and timings you'd see from AWS.

Move existing data​

The simplest, fastest move is rclone:

# rclone config — set up two remotes:
#   aws-s3   (Amazon S3 with your AWS keys)
#   filebase (Other → s3.filebase.io with your Filebase keys)

rclone copy aws-s3:my-source-bucket filebase:my-dest-bucket \
  --transfers 16 \
  --checkers 32 \
  --progress

This streams objects directly between providers without writing to local disk. For small/medium buckets (< 10 TB), it's typically fast and reliable in one session.

For very large buckets:

  • Run rclone on a host close to AWS (an EC2 instance) to avoid AWS egress costs to your laptop.
  • Resume by re-running the same command — rclone skips already-copied files.
  • After the bulk copy, run rclone check aws-s3:src filebase:dst to verify.

Cutover strategies​

Big-bang cutover​

For workloads that can tolerate a short read-only window:

  1. Set the application to read-only / maintenance mode.
  2. Run the final rclone sync.
  3. Switch the application config to the new endpoint.
  4. Resume traffic.

Dual-write cutover​

For workloads that can't pause:

  1. Update application code to write to both AWS S3 and Filebase. Continue serving reads from AWS.
  2. Run a backfill rclone job to copy historical data.
  3. Once backfill is verified, flip reads to Filebase.
  4. Stop writing to AWS S3.
  5. (Eventually) decommission the AWS bucket.

Just stop writing to AWS​

For data that's mostly cold (logs, archives, backups):

  1. Update the application to write all new data to Filebase.
  2. Leave AWS S3 read-only for historical access.
  3. Migrate AWS data to Filebase in the background, on your own schedule.
  4. Eventually decommission the AWS bucket.

Cost comparison​

A worked example for a 10 TB workload with 5 TB/month egress:

AWS S3 StandardFilebase
Storage (10 TB)$235.52 / month$153.60 / month
Egress (5 TB)$460.80 / month$0
Total$696.32$153.60
Savings$542.72 / month

(Storage rates: AWS = $0.023/GB-mo, Filebase = $0.015/GB-mo. AWS egress = $0.09/GB after first GB. Both rates as of writing; check the Filebase pricing page for current.)

For workloads with significant egress, Filebase savings dominate.

Common gotchas​

  • Object-level ACLs. If you use them on AWS, you'll need to refactor — Filebase only supports bucket-level ACLs. Most apps don't actually rely on object-level ACLs; they just inherit AWS defaults.
  • Bucket policies. Not supported on Filebase. Use bucket ACLs and pre-signed URLs.
  • Lambda S3 triggers. AWS Lambda doesn't fire on Filebase events. Refactor to: app → write to Filebase → invoke Lambda directly.
  • AWS-specific features. S3 Object Lock, Replication, Inventory, Storage Lens — none of these have Filebase equivalents today. See the compatibility matrix.

What's next​