Getting Started

Getting Started

This guide will have you running Stowry and storing your first file in 5 minutes.

Prerequisites

• A terminal/command line
• curl for making HTTP requests (or any HTTP client)

Step 1: Download Stowry

Download the latest release for your platform:

# Linux (amd64)
curl -LO https://github.com/sagarc03/stowry/releases/latest/download/stowry-linux-amd64
chmod +x stowry-linux-amd64
mv stowry-linux-amd64 stowry

# macOS (arm64)
curl -LO https://github.com/sagarc03/stowry/releases/latest/download/stowry-darwin-arm64
chmod +x stowry-darwin-arm64
mv stowry-darwin-arm64 stowry

Step 2: Create Configuration

Create a config.yaml file:

server:
  port: 5708
  mode: store

database:
  type: sqlite
  dsn: stowry.db
  tables:
    meta_data: stowry_metadata

storage:
  path: ./data

auth:
  read: private
  write: private
  aws:
    region: us-east-1
    service: s3
  keys:
    inline:
      - access_key: AKIAIOSFODNN7EXAMPLE
        secret_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

log:
  level: info

Step 3: Database Setup

Run the init command to create the database schema:

./stowry init

The table name (stowry_metadata in this example) must be lowercase, use only alphanumeric characters and underscores, and be at most 63 characters long.

Alternative: Manual Migration

If you prefer to manage the schema yourself, run the SQL manually:

SQLite

CREATE TABLE IF NOT EXISTS stowry_metadata (
    id TEXT NOT NULL PRIMARY KEY,
    path TEXT NOT NULL UNIQUE,
    content_type TEXT NOT NULL,
    etag TEXT NOT NULL,
    file_size_bytes INTEGER NOT NULL,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    deleted_at TEXT,
    cleaned_up_at TEXT
);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_deleted_at
ON stowry_metadata (deleted_at);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_pending_cleanup
ON stowry_metadata (deleted_at, cleaned_up_at);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_active_list
ON stowry_metadata (created_at, path);

PostgreSQL

CREATE TABLE IF NOT EXISTS stowry_metadata (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    path TEXT NOT NULL UNIQUE,
    content_type TEXT NOT NULL,
    etag TEXT NOT NULL,
    file_size_bytes BIGINT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ,
    cleaned_up_at TIMESTAMPTZ
);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_deleted_at
ON stowry_metadata (deleted_at)
WHERE (deleted_at IS NOT NULL);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_pending_cleanup
ON stowry_metadata (deleted_at, cleaned_up_at)
WHERE (deleted_at IS NOT NULL AND cleaned_up_at IS NULL);

CREATE INDEX IF NOT EXISTS idx_stowry_metadata_active_list
ON stowry_metadata (created_at, path)
WHERE (deleted_at IS NULL);

Step 4: Start the Server

./stowry serve

You should see:

INFO starting server addr=:5708 mode=store

Step 5: Upload a File

Stowry uses presigned URLs for authentication. For this quick test, enable public write access temporarily by setting auth.write: public in your config, then restart the server.

Upload a file:

curl -X PUT \
  -H "Content-Type: text/plain" \
  -d "Hello, Stowry!" \
  http://localhost:5708/hello.txt

Using stowry-cli:

echo "Hello, Stowry!" > hello.txt
stowry-cli upload hello.txt

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "hello.txt",
  "content_type": "text/plain",
  "etag": "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e",
  "file_size_bytes": 14,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Step 6: Download the File

curl http://localhost:5708/hello.txt

Using stowry-cli:

stowry-cli download hello.txt

Output:

Hello, Stowry!

Step 7: Use Presigned URLs (Production)

For production, disable public access and use presigned URLs. See the Authentication guide for generating presigned URLs with the stowry-go SDK or AWS SDK.

import stowry "github.com/sagarc03/stowry-go"

client := stowry.NewClient(
    "http://localhost:5708",
    "AKIAIOSFODNN7EXAMPLE",
    "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
)

// Generate a presigned URL valid for 15 minutes
uploadURL := client.PresignPut("/photos/vacation.jpg", 900)

Next Steps

• Installation - More installation options
• Configuration - Full configuration reference
• Authentication - Presigned URL authentication
• Server Modes - Store, Static, and SPA modes