Storage Configuration

Baan stores article bodies, images, uploaded media, and generated files such as llms.txt in a pluggable storage backend. SQLite/libSQL stores operational data such as settings, users, sessions, article metadata, the article index, API keys, and rate-limit counters.

You can switch between storage providers from the admin panel without rebuilding the app. The System settings flow can copy existing content to the new provider before Baan starts using it.

Providers at a Glance

| Provider | Environments | Best For | |----------|-------------|---------| | local | Self-hosted only | Simple setups, development, single-server deployments (local filesystem) | | gcs | All | Google Cloud users; integrates well with GKE, Cloud Run | | s3 | All | AWS users; widest ecosystem and tooling | | r2 | All | Cost-conscious teams; free egress from Cloudflare’s network |

Caution

The local filesystem provider is not available on serverless platforms (Vercel, etc.) because their file system does not persist between function invocations. Use GCS, S3, or R2 for serverless deployments.

How to Switch Providers

1. Go to Admin → Settings → System
2. Select the new storage provider and enter credentials
3. Click Migrate to copy existing content to the new location
4. Save — Baan starts using the selected provider after the migration/switch completes

No rebuild is required. Runtime switching is handled through the provider value saved in the database.

---

Local Filesystem

Files are saved to the content/ directory in the project root.

No environment variables needed. The provider is selected during setup and stored in the database.

When using Docker, mount the content/ directory as a volume so files persist across container restarts:

volumes:
  - ./content:/app/content

Tip

The local filesystem provider is the simplest option for single-server setups or development. If you later move to cloud storage, use the migration tool in Admin → Settings → System.

---

Google Cloud Storage (GCS)

Caution

Do not grant the service account broad project-wide roles such as Owner or Editor. Use only the Storage Object Admin role shown below — it is scoped to Cloud Storage objects and gives Baan exactly the access it needs (read, write, delete, list) without exposing other GCP services.

Step 1 — Create a Bucket

1. Go to console.cloud.google.com → Cloud Storage
2. Create a bucket in your preferred region

Step 2 — Create a Service Account

1. Go to IAM & Admin → Service Accounts → Create Service Account
2. Give it a name (e.g. baan-gcs-access) — the service account ID is auto-filled

3. Click Create and continue
4. Under Grant this service account access to project, select the role Storage Object Admin

5. Click Done

Step 3 — Create a JSON Key

1. Open the service account you just created → Keys tab
2. Click Add Key → Create new key

3. Select JSON (recommended) → Create

4. The JSON key file downloads automatically. Store it securely — it cannot be re-downloaded if lost

Step 4 — Base64-encode the Credentials

Baan reads the credentials from a single environment variable, so the JSON file must be encoded as one line.

Option A — Encode in your browser (no upload, no storage):

🔒 Encoded entirely in your browser. The file is never uploaded, never logged, and never stored.

📄 Click to select your service-account JSON or drag and drop

Option B — Encode from your terminal:

base64 -i service-account.json | tr -d '\n'

On Linux, use base64 -w 0 service-account.json instead.

Environment Variables

GOOGLE_CLOUD_PROJECT_ID=your-project-id
GCS_BUCKET_NAME=your-bucket-name
GOOGLE_CLOUD_CREDENTIALS_BASE64=base64-encoded-service-account-json

The GOOGLE_CLOUD_CREDENTIALS_BASE64 value is the entire contents of the JSON key file, Base64-encoded as a single line with no line breaks.

---

Amazon S3

Create a Bucket

1. Go to the S3 console → Create bucket
2. Choose a region close to your users
3. Keep “Block all public access” enabled (Baan accesses files directly, not via public URLs)

Caution

Do not attach the managed policy AmazonS3FullAccess. It grants read/write/delete on every S3 bucket in your AWS account — including buckets unrelated to Baan. If the access key leaks, the blast radius is your entire S3 account, not just the Baan bucket. Always create a custom policy scoped to a single bucket using the steps below.

Step 1 — Create a Custom IAM Policy

Create the policy first, then attach it to the IAM user in Step 2.

1. Go to IAM → Policies → Create policy
2. Switch to the JSON tab and paste the policy below — replace your-bucket-name with your actual bucket name

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BaanS3Access",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    },
    {
      "Sid": "BaanS3List",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::your-bucket-name"
    }
  ]
}

3. Click Next → give the policy a name (e.g. baan-s3-access) → Create policy

Step 2 — Create an IAM User and Attach the Policy

1. Go to IAM → Users → Create user — give it a name (e.g. baan-s3-access)

2. On the Set permissions screen, choose Attach policies directly, search for the policy you created in Step 1 (e.g. baan-s3-access), and select it

3. Click Next → review the user and confirm the policy is attached → Create user

The user appears in the IAM users list once created.

Step 3 — Create an Access Key

1. Open the user you just created → Security credentials tab → under Access keys, click Create access key

2. Select Application running outside AWS as the use case → Next

3. Save the Access key ID and Secret access key — the secret is shown only once and cannot be retrieved later

Environment Variables

AWS_REGION=ap-northeast-1
AWS_S3_BUCKET_NAME=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

---

Cloudflare R2

R2 is S3-compatible and has no egress fees — your readers don’t pay bandwidth costs when assets are served from R2.

Create a Bucket

1. Go to your Cloudflare dashboard → R2
2. Click Create bucket

Create an API Token

1. In R2 → Manage R2 API Tokens → Create API Token
2. Set permissions to Object Read & Write for your bucket

Environment Variables

CF_ACCOUNT_ID=your-cloudflare-account-id
CF_R2_BUCKET_NAME=your-bucket-name
CF_R2_ACCESS_KEY_ID=your-api-token-key-id
CF_R2_SECRET_ACCESS_KEY=your-api-token-secret

Your CF_ACCOUNT_ID is shown in the right sidebar of any Cloudflare dashboard page.

---

Content Directory Structure

Regardless of which provider you use, Baan organizes content in the same directory layout:

content/
├── article-slug/
│   ├── index.en.md         # always index.{locale}.md — e.g. en, ja, fr
│   └── images/
│       └── hero.jpg
│
├── another-article/
│   ├── index.ja.md         # multi-language: one file per locale
│   ├── index.en.md
│   └── images/
│
└── _settings/              # internal — do not modify manually
    └── ...

System folders prefixed with _ (such as _settings/ and _auth/) are hidden in the Media Library and managed by Baan automatically.

---

How Images Are Served to Readers

Images referenced in articles are never exposed as direct signed storage URLs in the rendered HTML. Instead, Baan replaces them with stable proxy URLs:

/api/image?path=article-slug/images/photo.jpg

When a reader’s browser requests this URL, Baan generates a fresh signed URL from your storage provider and redirects the browser to it. The signed URL result is cached server-side for 24 hours — so repeated requests to the same image do not hit your storage API.

When you save or delete a post in the admin panel, Baan clears the image cache alongside the page cache, so updated images appear immediately.

Signed URL expiry (GCS / S3 / R2) is set to 48 hours — longer than the 24-hour server cache — to ensure the redirected URL is still valid for any visitor who lands on a cached response just before it is refreshed.