# Store data, files and secrets

> How every app keeps its own records, files and keys in your cloud, what to ask your coding agent and what IT sees.

Source: https://diakrin.com/docs/app-data

Every app owns its own database, file storage and secrets in your company cloud from the moment it is created, so a builder and their coding agent use them without asking IT for anything.

## What each app owns

| Resource | What the app owns | App code uses |
|---|---|---|
| Data | Its own database and role in the setup's Postgres | `ctx.db` |
| Files | Its own private area in the setup's file storage | `ctx.files` |
| Secrets | Its own secret store, filled by a person, never by the agent | `ctx.secrets` |

There is nothing to request, declare or wait for. The app's `diakrin.json` lists the three, so anyone reading the code sees what the app owns. Preview and Production share the app's data, files and secrets: what people save in Preview is there in Production, so try things with made-up rows.

> [!NOTE]
> Files and secrets are available on AWS setups that have the file storage update. On Google Cloud setups they are not available yet; data works as before.

## What to ask your coding agent

Say what you want in your own words. The agent maps it like this:

| The person says | The agent does | The agent says |
|---|---|---|
| remember, save, track, list | a table in `migrations/`, routes with `ctx.db` | "It will remember them." |
| attach, upload, photo, document, export file | `ctx.files`, the id in a table with its owner, an `upload: true` route, kit file field | "People can attach files." |
| key, password, token, webhook for X | `app.secret.request`, `ctx.secrets.require(NAME)`, the name in `diakrin.json` | "Open this link and paste the key. Don't paste it here." |
| company system data | integration tools, IT approval | IT approves access first. |

The agent never writes files to the app's disk, puts a key in the code, reads a key from environment variables, calls a cloud SDK or asks you for a key in the chat. Every save is checked for writes to the app's disk (`STORAGE_LOCAL_DISK`), a cloud SDK (`STORAGE_CLOUD_SDK`), a secret name the code reads that `diakrin.json` does not list (`MANIFEST_SECRET_UNDECLARED`) and a recognizable key or password written into the code (`SECRET_DETECTED`); each one stops the version until the agent fixes it. The other rules are the agent's instructions, not checks.

### When files or secrets are not turned on yet

Files and secrets work only on a setup where Diakrin has turned them on. The agent checks first and follows this rule:

> Before building on files or secrets, call `app.resources.get`. Build attachments on `ctx.files` when `files.supported` is true, when `files.reason` is `APP_UPDATE_PENDING` (the app's next saved version connects its file area; a new app's first save does), or when it is `FILES_STATUS_UNKNOWN` (Diakrin cannot confirm it right now: build them and call `app.resources.get` again after the save). When `files.reason` is `FILES_NOT_ENABLED`, `GATEWAY_UPDATE_PENDING` or `FAST_PATH_REQUIRED`, or `app.secret.request` answers `SECRETS_NOT_ENABLED`, Diakrin has not turned it on for this app's setup yet: build the rest without that feature, never around it, and tell the person in plain words that it comes later. When `files.reason` is `SETUP_UPDATE_REQUIRED` (`files.responsible` is it), IT must update the company cloud setup first: build the rest without attachments and tell the person that IT acts. When `files.reason` is `SETUP_NOT_SUPPORTED`, this cloud has no app files: build the rest without attachments, say so in plain words and never promise them. Use `ctx.secrets` once `app.secret.request` has named the key, then save a new version: that update also connects the app's secret store if it is not connected yet.

So on such a setup the agent builds the rest of the app and tells you in plain words that attachments or a key come later, and who acts: Diakrin, or IT when the company cloud setup needs an update.

## Store files

- People attach a file on the app's page. The app keeps it in its own private area and remembers who it belongs to.
- A file can be at most 25 MB.
- PNG, JPEG, GIF, WebP and PDF files open in the page. Every other type downloads as a file, so an uploaded web page can never run inside the app.
- Apps cannot read each other's files. The app's own cloud role and the bucket policy both enforce this.

## Use a secret

When the app needs a key, password, token or webhook, for example to post new orders to Slack:

```steps
Request | Coding agent | Asks Diakrin for the secret by name, for example SLACK_WEBHOOK, and gives you a link.
Enter | App owner or IT | Opens the link, signs in to Diakrin and enters the value on that page.
Use | The app | Reads the value within about a minute. No new save is needed.
```

> [!WARNING]
> Enter a secret only on the Diakrin page the link opens. Never paste it into the chat, the code or a file. If a key was pasted into the chat by mistake, replace it at its source (for example create a new Slack webhook) and enter the new one on the page.

- Only the app's owner or IT can enter or remove a value. Your company can restrict this to IT only.
- The value is encrypted in your browser for a key that lives in your company cloud. Diakrin keeps only the name, who entered it and when.
- Until a value is entered, the app says "SLACK_WEBHOOK has not been set yet. Ask the app's owner to enter it in Diakrin."
- Removing a value takes effect within about a minute only when the app reads it inside a request handler. An app that reads it once at start keeps running with the old value until its next version. If a key leaked, also revoke it at its source (for example delete the Slack webhook).

## Run the app on your computer

Before you start, you need an app folder from `diakrin pull` or `diakrin app start`, and Docker running for the local database.

```sh
diakrin dev --root <app folder>
```

The app starts at an `http://127.0.0.1` address and works without any cloud access:

| Resource | On your computer |
|---|---|
| Data | A private Postgres on this computer |
| Files | The `.diakrin/files/` folder inside the app folder. It is never saved to Diakrin: a save that contains it is refused. |
| Secrets | The placeholder `local-<NAME>` for each name listed in `diakrin.json` |

The result lists each secret name with `placeholder` or the variable its value came from, never a value. To try a real key on your own computer, set `DIAKRIN_LOCAL_SECRET_<NAME>` in your own terminal, not through your coding agent, before you start the app. Only names listed in `diakrin.json` are passed to the app, and no cloud credential from your terminal ever reaches it.

## What IT sees in the company cloud

| In your AWS account | What it is |
|---|---|
| One file bucket per setup, `diakrin-files-<account>-<setup>` | Each app has its own area `apps/<app id>/`, encrypted with the setup's own key, versioned and never public |
| One secret per app, `diakrin/app/<app id>/secrets-<id>` | The app's values as one map. Diakrin roles other than the app's own role and the setup's secret intake are denied the value |
| One database per app, `app_<id>` | In the setup's Postgres, as before |

Each app's role can reach only its own file area and its own secret. Nothing is copied to Diakrin: file bytes move between the app and the bucket inside your cloud.

### App files need a cloud update

When the setup's page in Diakrin shows "App files: Needs a cloud update", the setup's file bucket exists but the setup's private network cannot reach it yet. Until it can, apps on that setup are built without attachments. Data and secrets are not affected.

- **A setup on a network Diakrin created:** apply the foundation update (foundation 3.2.0). It adds one statement, `SetupFileBuckets`, to the setup's S3 gateway endpoint policy and changes nothing else.
- **A setup on your company's own network whose S3 endpoint has its own policy:** allow the same statement on that endpoint policy.

The statement allows only the five file actions, only on this account's `diakrin-files-` buckets and their objects:

```json
{
  "Sid": "SetupFileBuckets",
  "Effect": "Allow",
  "Principal": "*",
  "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket", "s3:GetBucketLocation"],
  "Resource": ["arn:aws:s3:::diakrin-files-<account>-*", "arn:aws:s3:::diakrin-files-<account>-*/*"],
  "Condition": { "StringEquals": { "aws:ResourceAccount": "<account>" } }
}
```

Diakrin checks the setup again on its own, and the setup page changes once the bucket is reachable. Which app may use which file area is enforced by the bucket policy and each app's role, not by the endpoint.

## If it fails

| Symptom | Cause | Fix |
|---|---|---|
| The app says a key "has not been set yet" | Nobody has entered the value | The app owner or IT opens the link from the agent and enters it. |
| The app says "File storage is not turned on for this app yet." | Files are not turned on for the app's setup yet | Diakrin turns them on for AWS setups (not yet on Google Cloud). When the company cloud setup needs an update first, the setup's page in Diakrin says so and IT applies it: see [App files need a cloud update](/docs/app-data#app-files-need-a-cloud-update). Data keeps working meanwhile. |
| "This file is larger than 25 MB." | The file is over the limit | Attach a smaller file. |
| A save stops with `STORAGE_LOCAL_DISK` | The code writes files to the app's disk | Ask the agent to store them with `ctx.files`. |
| A save stops with `STORAGE_CLOUD_SDK` | The code imports a cloud SDK | Ask the agent to remove it and use `ctx.files` or `ctx.secrets`. |
| A save stops with `MANIFEST_SECRET_UNDECLARED` | The code reads a secret that `diakrin.json` does not list | Ask the agent to add the name to `resources.secrets` in `diakrin.json`. |
| A save is refused with `LOCAL_PATH_REFUSED` | The save included the local `.diakrin/` folder | Leave `.diakrin/` out. Local files stay on your computer. |

## Next

Save a version and get a Preview: [Preview, approve and deploy](/docs/deploy).
