Static site / public asset hosting

Goal: serve assets directly from K3 over plain GET URLs — no presigning, no auth headers — for things like images, fonts, downloads, or a static-site build.

Why: presigning every URL is overkill for assets meant to be public. K3 supports a per-bucket access_mode that lets anonymous reads through while keeping writes locked to the bucket owner.

Two hosts, two jobs. You upload over the signed S3 wire object.uk-lon-1.dodil.io, and readers fetch over the control-plane route api.data.dodil.io/orgs/<org>/…. Only the second one serves anonymous requests: the object endpoint refuses any request without a credential with 401 AccessDenied before it looks at the bucket, and has no /orgs/ route. Per-bucket CORS is evaluated on the control-plane route too.

Not a CDN. K3 doesn’t do edge caching. For high-traffic public content, put a CDN (Cloudflare, Fastly, CloudFront) in front of the K3 endpoint — the recipe below is the origin.

1. Create a public bucket

bucket create has no --access-mode flag, so a new bucket starts PRIVATE and you flip it:

dodil data bucket create assets-public -d "Public assets"
dodil data bucket update assets-public --access-mode public
 
# ...or flip an existing bucket
dodil data bucket update kb-prod --access-mode public

The three access modes (from Core Concepts → Bucket):

Once public, any GET to https://api.data.dodil.io/orgs/<org>/<bucket>/<key> succeeds without an Authorization header. <org> is your org slug.

2. Configure CORS (if assets are loaded cross-origin)

Browsers enforce CORS on cross-origin fetches for fonts, JSON, ES modules, and any fetch()-loaded resource. <img> / <video> tags don’t need CORS unless you read pixel data via canvas.

cat > cors.json <<'EOF'
{
  "corsRules": [
    {
      "allowedOrigins": ["*"],
      "allowedMethods": ["GET", "HEAD"],
      "allowedHeaders": ["*"],
      "exposeHeaders": ["ETag", "Content-Length", "Content-Type"],
      "maxAgeSeconds": 86400
    }
  ]
}
EOF
 
dodil data bucket cors set assets-public -f cors.json

Lock allowedOrigins to your real domains in production.

3. Upload your assets

# One-shot: copy a built site
aws s3 sync ./dist s3://assets-public/site/ --delete
 
# With proper content-type / cache headers — important for static sites
aws s3 sync ./dist s3://assets-public/site/ \
  --cache-control "public, max-age=31536000, immutable" \
  --exclude "*.html" \
  --delete
 
# Re-sync HTMLs with short TTL
aws s3 sync ./dist s3://assets-public/site/ \
  --cache-control "public, max-age=60" \
  --exclude "*" --include "*.html"

# A whole build directory — --recursive walks the tree and --key is the key prefix,
# so ./dist/css/app.css lands at site/css/app.css
dodil data object create ./dist --recursive -b assets-public -k site
 
# Or one file at a time
dodil data object create ./dist/index.html -b assets-public -k site/index.html

# .github/workflows/deploy.yml
- name: Deploy to K3
  env:
    AWS_ACCESS_KEY_ID:     ${{ secrets.DODIL_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.DODIL_SECRET_ACCESS_KEY }}
    AWS_REGION:            us-east-1
    AWS_ENDPOINT_URL:      https://object.uk-lon-1.dodil.io
  run: |
    aws s3 sync ./dist s3://assets-public/site/ \
      --cache-control "public, max-age=31536000, immutable" \
      --exclude "*.html" --delete
 
    aws s3 sync ./dist s3://assets-public/site/ \
      --cache-control "public, max-age=60" \
      --exclude "*" --include "*.html"

4. Reference assets in your app

<!-- Image -->
<img src="https://api.data.dodil.io/orgs/<org>/assets-public/site/logo.svg" alt="logo" />
 
<!-- Download link -->
<a href="https://api.data.dodil.io/orgs/<org>/assets-public/site/whitepaper.pdf">Download whitepaper</a>
 
<!-- Stylesheet -->
<link rel="stylesheet" href="https://api.data.dodil.io/orgs/<org>/assets-public/site/app.css" />
 
<!-- ES module -->
<script type="module" src="https://api.data.dodil.io/orgs/<org>/assets-public/site/app.js"></script>

URLs are stable: https://api.data.dodil.io/orgs/<org>/<bucket>/<key>.

Cache-control matters

S3 (and therefore K3) returns the Cache-Control header you set on the object at upload time. Get this right or you’ll either ship stale builds or DDoS your origin:

aws s3 sync --cache-control sets the header at upload time. After upload, dodil data object show <key> -b <bucket> -o json confirms what was stored.

Putting a CDN in front

K3 is the origin, not the edge. For high-traffic public content, add a CDN:

The origin is the control-plane host — a CDN fetches anonymously, so pointing it at object.uk-lon-1.dodil.io gets you a wall of 401s.

Cloudflare:

• DNS: assets.example.com → CNAME → <some-cloudflare-cname>
• Cloudflare origin: https://api.data.dodil.io, with an origin rule prefixing /orgs/<org>/assets-public onto the path
• Use the path-style URL — K3 requires it
• Set Cloudflare cache rules: respect origin Cache-Control

CloudFront:

• Origin: api.data.dodil.io
• Origin path: /orgs/<org>/assets-public (so CF requests /foo from K3 land at assets-public/foo)
• Cache policy: CachingOptimized (respects origin headers)
• Leave origin request signing off — the bucket’s PUBLIC access mode is what authorizes the fetch

Limitations vs. S3-website / R2-Custom-Domains

K3 does not currently implement:

• Website endpoint (?website bucket config — index documents, error documents, redirect rules). Route / to index.html at the CDN layer or in your app.
• Custom domains on the K3 endpoint directly. Use a CDN as the public name and K3 as the origin.

Both are roadmap, not in production today.

Common gotchas

See also

• Browser Upload — for user-uploaded public content
• Mirror from AWS S3 — moving existing public assets into K3
• CORS — API Reference — full CORS rule shape
• Bucket — Core Concepts — access modes