Quickstart

LiveVerification Required

ObjectDB S3 Core quickstart.

Run a local ObjectDB service, create an S3 Core bucket, upload and read one object, list the bucket, and verify that a request outside the active S3 Core profile fails explicitly.

Current availability

Private Beta. Public beta is scheduled for September 7, 2026.

Result

You will have a local ObjectDB S3 Core workflow that creates photos-docs-022, writes raw/cat.txt, reads back object-body, lists the visible key, and confirms that bucket versioning returns a S3-shaped NotImplemented response.

Maturity Status

S3 Core Workflow

Live

Bucket create, object put/get, and ListObjectsV2 are part of the active s3-core-v1 gateway surface documented by ObjectDB.

Review Boundary

Verification Required

This tutorial proves a local first-success path only. Broader durability, availability, performance, support, security, and scale claims still need evidence review.

Prerequisites

Required tools

Required

cargo --version for the Rust toolchain
curl --version for S3-shaped HTTP requests
git --version and a local ObjectDB source checkout

Product setup

Required

ObjectDB source at /path/to/Service.ObjectDB or an equivalent local checkout.
OBJECTDB_BIND_ADDRESS set to an unprivileged loopback port, such as 127.0.0.1:18080.
OBJECTDB_DATA_DIR set to a disposable tutorial directory.

Optional helpers

Optional

An AWS CLI or S3-compatible client can replay the same path-style operations once credentials and signing are configured.
jq is useful for later JSON examples, but this quickstart verifies XML and headers directly.

See local prerequisites for the shared tool baseline.

Start The Service

Use a dedicated terminal for the ObjectDB process and keep it running while you complete the workflow from another terminal.

Run ObjectDB locally

Service terminal

cd /path/to/Service.ObjectDB
export OBJECTDB_BIND_ADDRESS=127.0.0.1:18080
export OBJECTDB_DATA_DIR="${TMPDIR:-/tmp}/objectdb-docs-022"
mkdir -p "$OBJECTDB_DATA_DIR"
cargo run --package objectdb

Expected output

Cargo builds the objectdb package, then starts target/debug/objectdb.
Keep this terminal open. If bind fails, choose another loopback port and update OBJECTDB_ENDPOINT below.

Check readiness

Workflow terminal

export OBJECTDB_ENDPOINT=http://127.0.0.1:18080
curl -i "$OBJECTDB_ENDPOINT/health"

Expected output

HTTP/1.1 200 OK

"Healthy"

Complete The Workflow

Configure tutorial values

Copy/paste

Run this in a second terminal while the ObjectDB service keeps running.

export OBJECTDB_ENDPOINT=http://127.0.0.1:18080
export OBJECTDB_BUCKET=photos-docs-022
export OBJECTDB_KEY=raw/cat.txt
export OBJECTDB_BODY_FILE=/tmp/objectdb-docs-022-body.txt
printf 'object-body' > "$OBJECTDB_BODY_FILE"

Expected output

The body file is 11 bytes:

wc -c "$OBJECTDB_BODY_FILE"
11 /tmp/objectdb-docs-022-body.txt

Create a bucket

Copy/paste

Create one tutorial-scoped bucket through the path-style S3 Core route.

curl -i -X PUT \
  -H "x-amz-request-id: docs-022-create-bucket" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET"

Expected output

HTTP/1.1 200 OK
location: /photos-docs-022
x-objectdb-s3-profile: s3-core-v1
x-objectdb-s3-operation: CreateBucket
x-objectdb-s3-bucket-id: bucket-...

Put an object

Copy/paste

Upload a small object with a request ID and content type. UNSIGNED-PAYLOAD keeps the copy/paste path focused on ObjectDB behavior instead of shell-specific checksum tools.

curl -i -X PUT \
  -H "x-amz-request-id: docs-022-put-object" \
  -H "x-amz-content-sha256: UNSIGNED-PAYLOAD" \
  -H "Content-Type: text/plain" \
  --data-binary @"$OBJECTDB_BODY_FILE" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET/$OBJECTDB_KEY"

Expected output

HTTP/1.1 200 OK
x-objectdb-s3-operation: PutObject
x-objectdb-s3-body-streamed-bytes: 11
x-objectdb-s3-object-id: object-...
x-objectdb-s3-version-id: version-...
x-objectdb-s3-put-object-contract: objectdb-s3-put-object-2026-08

Get the object

Copy/paste

Read the object back and confirm the gateway returns the same payload and object metadata.

curl -i \
  -H "x-amz-request-id: docs-022-get-object" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET/$OBJECTDB_KEY"

Expected output

HTTP/1.1 200 OK
content-length: 11
content-type: text/plain
x-objectdb-s3-operation: GetObject
x-objectdb-s3-logical-size-bytes: 11

object-body

List the bucket

Copy/paste

Use ListObjectsV2 with a prefix to prove the current key is visible.

curl -i \
  -H "x-amz-request-id: docs-022-list-objects" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET?list-type=2&prefix=raw/"

Expected output

HTTP/1.1 200 OK
x-objectdb-s3-operation: ListObjectsV2
x-objectdb-s3-list-key-count: 1

<ListBucketResult
<Name>photos-docs-022</Name>
<KeyCount>1</KeyCount>
<Key>raw/cat.txt</Key>

Check an unsupported S3 surface

Copy/paste

Ask for bucket versioning to see how ObjectDB responds when a request is outside the active S3 Core profile.

curl -i \
  -H "x-amz-request-id: docs-022-versioning-boundary" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET?versioning"

Expected output

HTTP/1.1 501 Not Implemented
x-objectdb-s3-profile: s3-core-v1
x-objectdb-s3-operation: GetBucketVersioning
x-objectdb-s3-error-code: NotImplemented

<Code>NotImplemented</Code>

Verify Success

The quickstart is successful when GetObject returns object-body, ListObjectsV2 includes raw/cat.txt, and the unsupported versioning request returns NotImplemented instead of silently succeeding.

Clean Up

Delete the object

Copy/paste

Remove the tutorial object before deleting the bucket.

curl -i -X DELETE \
  -H "x-amz-request-id: docs-022-delete-object" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET/$OBJECTDB_KEY"

Expected output

HTTP/1.1 204 No Content
x-objectdb-s3-operation: DeleteObject
x-objectdb-s3-delete-object-contract: objectdb-s3-delete-object-2026-08

Delete the bucket

Copy/paste

Delete the now-empty tutorial bucket.

curl -i -X DELETE \
  -H "x-amz-request-id: docs-022-delete-bucket" \
  "$OBJECTDB_ENDPOINT/$OBJECTDB_BUCKET"

Expected output

HTTP/1.1 204 No Content
x-objectdb-s3-operation: DeleteBucket
x-objectdb-s3-bucket-id: bucket-...

Stop local state

Copy/paste

Stop the service with Ctrl-C in the service terminal, then remove only the tutorial files.

rm -f "$OBJECTDB_BODY_FILE"
rm -rf "${TMPDIR:-/tmp}/objectdb-docs-022"

Expected output

The body file and tutorial data directory are gone. Do not remove any shared ObjectDB data directory.

Troubleshooting

Common first-run failures
Symptom	How to recognize it	Likely cause	Fix
Service does not start	`cargo run --package objectdb` reports that the address is already in use.	Another local process is using `127.0.0.1:18080`.	Choose a different loopback port in `OBJECTDB_BIND_ADDRESS` and update `OBJECTDB_ENDPOINT` to match.
Health check cannot connect	`curl` reports connection refused or times out.	The service terminal stopped, is still compiling, or is bound to a different address.	Wait for Cargo to finish, confirm the service terminal is still open, and re-check the endpoint value.
Bucket create returns `BucketAlreadyOwnedByYou`	The response status is `409 Conflict` with `<Code>BucketAlreadyOwnedByYou</Code>`.	The bucket name already exists in the current local service state.	Run cleanup or set `OBJECTDB_BUCKET` to a new tutorial-scoped name.
Put object returns `BadDigest`	The response body contains `<Code>BadDigest</Code>`.	A supplied checksum header does not match the uploaded body.	Use `x-amz-content-sha256: UNSIGNED-PAYLOAD` for this quickstart, or regenerate the checksum for the exact file.
Bucket delete returns `BucketNotEmpty`	The response status is `409 Conflict` with `<Code>BucketNotEmpty</Code>`.	At least one current object remains visible in the bucket.	Delete `raw/cat.txt`, then retry the bucket delete command.
Unsupported check does not return `NotImplemented`	The request does not show `x-objectdb-s3-operation: GetBucketVersioning`.	The query string or bucket endpoint is different from the documented `?versioning` shape.	Reuse the exact unsupported-surface command and confirm `OBJECTDB_BUCKET` still names the tutorial bucket.

Evidence

DOCS-022 evidence map
Workflow step	Evidence	Status
Service startup and health	Service.ObjectDB/ObjectDB/src/main.rs, ObjectDB/src/config.rs, and AutomatedTests/Health/HealthEndpointTests.cs	Source-backed; local run still needs reviewer acceptance
Bucket create, list, location, and delete	Service.ObjectDB/docs/S3_HTTP_GATEWAY.md and ObjectDB/src/handlers/s3_gateway_handler.rs bucket lifecycle tests	Source-backed
PutObject and GetObject	Service.ObjectDB/docs/S3_PUT_OBJECT.md, docs/S3_GET_HEAD_OBJECT.md, and gateway handler tests	Source-backed
ListObjectsV2	Service.ObjectDB/docs/S3_LIST_OBJECTS_V2.md and gateway handler ListObjectsV2 tests	Source-backed
Unsupported S3 surface	Service.ObjectDB/docs/S3_COMPATIBILITY_PROFILES.md and routed stub response for excluded operations	Source-backed

Limits

Scoped S3 Core

This quickstart exercises bucket lifecycle basics, single-object put/get, and ListObjectsV2 in the active s3-core-v1 profile.

Local Adapter

The workflow uses local service state and a disposable data directory. It does not make claims about other topologies or fault models.

Unsupported Families

Versioning, Object Lock, lifecycle, replication, inventory, notifications, SelectObjectContent, ACLs, and website hosting stay outside this quickstart.

Next Steps

Available now
Review ObjectDB evidence
Use the evidence index before expanding ObjectDB compatibility or product claims.
Available now
Read tutorial prerequisites
Check the local tool baseline and product-specific setup expectations for first-success tutorials.
Available: DOCS-058
Adapt SDK examples
Use illustrative Python boto3 and AWS SDK for JavaScript v3 examples after completing the local curl workflow.
Available: DOCS-038
Compare S3 Core behavior
Use the compatibility matrix to separate supported, partial, unsupported, preview, future, and review-bound S3 surfaces.