File Storage

Hedhog handles file uploads through @hed-hog/core's FileService. All uploaded content goes through a single storage adapter, selected once via an Integration Profile. Swap the provider later without touching application code or re-uploading existing files.

Status: ✅ Fully implemented — Local, S3, GCS, Azure Blob, and S3-compatible providers all work.

1. Create an Integration Profile (type Storage, pick a provider) at Settings → Integration Profiles
2. Fill in the provider's config fields (tables below)
3. Go to Settings → Configurations → File Storage and set Storage Profile to it
4. Upload a test file anywhere in the admin (e.g. your own avatar) and confirm the returned URL actually loads

1. A file is uploaded through any endpoint that calls FileService.upload()
2. FileService reads the file-storage-profile-id setting to find the active Integration Profile (type storage)
3. It maps that profile's provider-specific config JSON into the adapter the matching provider class expects (local disk, S3, GCS, Azure Blob, or an S3-compatible service)
4. The file is written via the adapter, a record is saved in the file table with the resulting URL/key and metadata, and the public URL is returned to the client

If no storage profile is configured yet, the server still starts normally — it just logs a warning on boot, and any upload attempt fails with No file storage profile configured until you set one. This is the expected state right after a fresh install.

1. Go to Settings → Integration Profiles → New → Type Storage, pick a provider, and fill in its config fields (table below)
2. Go to Settings → Configurations → File Storage and set the Storage Profile field (file-storage-profile-id) to that profile
3. Uploads immediately start using the new provider — existing file records and their URLs are not migrated or rewritten, since Hedhog has no way to know whether old files should move

Stores files on the server filesystem. Suitable for development or single-server deployments — not recommended once you run more than one API instance, since uploads written by one instance won't be visible to the others.

Make sure the API process has write permission to this directory, and that it survives deploys/restarts (don't point it inside a directory your deploy pipeline wipes).

IAM permissions needed, scoped to the bucket:

{
  "Effect": "Allow",
  "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
  "Resource": "arn:aws:s3:::your-bucket/*"
}

Decide up front whether the bucket serves files publicly or via signed URLs — that's a bucket policy decision made in the S3 console, not a Hedhog setting.

Create the service account under IAM & Admin → Service Accounts, grant it the Storage Object Creator and Storage Object Viewer roles, then Keys → Add Key → JSON and paste the downloaded file's contents into key_file_json.

Find the account name and key in the Azure portal under Storage account → Access keys. The container must already exist — Hedhog does not create it automatically.

Use this provider for anything that speaks the S3 API but isn't AWS itself.

Without endpoint set, requests go to AWS's own endpoints and will fail against any non-AWS service — this is the single field people most often forget when switching from S3 to a compatible provider.

• Upload a file anywhere in the admin (a user avatar works well) and confirm a new row appears in file
• Open the returned URL directly in a browser tab — it should load the file, not 404 or hang