Build apps
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.
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.
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:
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:
- RequestCoding agent
Asks Diakrin for the secret by name, for example SLACK_WEBHOOK, and gives you a link.
- EnterApp owner or IT
Opens the link, signs in to Diakrin and enters the value on that page.
- UseThe app
Reads the value within about a minute. No new save is needed.
- 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.
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:
{
"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. 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.