Skip to main content

Getting Started

This guide takes you through the full first-use path: configure the service, upload one object, create a download link, and verify replication progress.

What You Will Learn​

  • which dependencies are required
  • how to configure and run the service
  • what success looks like after upload
  • how to inspect background replication

Prerequisites​

  • Go 1.24+
  • PostgreSQL

Helpful locally:

  • psql for metadata inspection
  • a small file such as sample.txt for testing

Step 1: Configure The Service​

Create .env in distributed-object-storage/.env:

DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=object_storage
DB_HOST=localhost
DB_PORT=5432
DB_SSLMODE=disable
APP_SECRET=replace_with_strong_secret

APP_SECRET signs presigned download URLs. Use a real secret outside local development.

The service currently uses these fixed runtime values:

  • HTTP bind: :8080
  • storage nodes: storage/node1, storage/node2, storage/node3

Run from repository root so .env is discovered automatically by startup.

Step 2: Prepare The Database​

Current behavior:

  • schema migrations are auto-applied at startup
  • applied migration versions are tracked in schema_migrations

You only need a reachable PostgreSQL database matching your .env values.

Step 3: Start The Service​

go run ./core/cmd/server

Default address:

  • http://localhost:8080

Step 4: Upload One Object​

curl -X POST \
  --data-binary @./sample.txt \
  -H "Content-Type: text/plain" \
  http://localhost:8080/upload/my-bucket/docs/sample.txt

After a successful upload:

  • the primary file should exist under storage/node1/...
  • metadata should exist in PostgreSQL
  • a durable replication job should be queued
curl http://localhost:8080/presign/my-bucket/docs/sample.txt

Expected shape:

{"url":"/download/my-bucket/docs/sample.txt?expires=...&signature=..."}

Step 6: Download The Object​

curl "http://localhost:8080/download/my-bucket/docs/sample.txt?expires=...&signature=..."

Step 7: Verify Replication Progress​

SELECT id, status, attempt_count, last_error
FROM replication_jobs
ORDER BY id DESC
LIMIT 20;

What to expect:

  • pending or running shortly after upload is normal
  • completed means secondary replication finished
  • failed means retries were exhausted and intervention is needed

To inspect retry schedule:

SELECT id, status, attempt_count, max_attempts, next_run_at, last_error
FROM replication_jobs
ORDER BY id DESC
LIMIT 20;

What You Just Proved​

You exercised the whole current product loop:

upload -> durable metadata -> queued replication -> presign -> download

That is the smallest useful slice of the system.