{"doc":"cdn","title":"Host files on cdn.gamestage.ai","markdown":"# Host files on cdn.gamestage.ai\n\nPublish a file that Studio or a game's clients fetch by URL, such as an App\nSpec document or your organisation's logo, at an address that never changes.\n\n```\n$ gamestage cdn put spec.json --app predictor --app-version 1.0.0\nPublished spec.json for predictor 1.0.0. It will never change at this address.\n  URL                https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/spec.json\n  Type               application/json\n  Size               2114 bytes\n  SHA-256            9f2c4e...\n```\n\nGive Studio that URL. Studio's spec fetcher gets the file with a `200`, and so\ndoes any browser, from any page.\n\nPublishing needs an organisation admin: the owner of a workspace that a\nMonterosa operator has made an admin of the organisation. Anybody else in the\norganisation can list the files.\n\n## Publish a file\n\n1. Name the app the file belongs to with `--app`, and its version with\n   `--app-version`.\n2. Run `gamestage cdn put <file> --app <app> --app-version <version>`.\n3. Copy the URL it prints. The file is served from that URL straight away.\n\nThe file keeps its own name unless you pass `--name`. Each file is one name,\nwith no folders, so publish an App Spec's documents one at a time under the\nsame app and version:\n\n```\ngamestage cdn put spec.json --app predictor --app-version 1.0.0\ngamestage cdn put elements.json --app predictor --app-version 1.0.0\ngamestage cdn put preview.html --app predictor --app-version 1.0.0\n```\n\n## Change a published file\n\nPublish it under a new version. A file at an address is never replaced, because\nStudio and every client that fetched it keep what they fetched: Studio\nregisters an App Spec URL once, and the file is served with a cache header of a\nyear.\n\n```\ngamestage cdn put spec.json --app predictor --app-version 1.0.1\n```\n\nThen point Studio at the new URL. The old version stays where it was.\n\n## List your organisation's files\n\n```\n$ gamestage cdn ls --app predictor\nnba's files on cdn.gamestage.ai, 3 in all:\n  https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/elements.json  5120 bytes\n  https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/preview.html  830 bytes\n  https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/spec.json  2114 bytes\n```\n\nLeave out `--app` to list every app's files.\n\n## Reference\n\n### `gamestage cdn put <file>`\n\n| Option | Type | Required | Default | What it does |\n| --- | --- | --- | --- | --- |\n| `<file>` | path | Yes | | The file to publish. JSON, HTML, PNG, JPEG, SVG or WebP, up to 2 MB (2,097,152 bytes). |\n| `--app <app>` | string | Yes | | The app it belongs to. Lowercase letters, numbers and hyphens, up to 63 characters. |\n| `--app-version <version>` | string | Yes | | Its version: `major.minor.patch`, such as `1.0.0`, with an optional pre-release such as `1.0.0-rc.1`. |\n| `--name <name>` | string | No | The file's own name | The name to publish it as. Letters, numbers, dots, hyphens and underscores, ending in one of the extensions below. |\n| `--org <id>` | string | No | Your organisation | Publish as another organisation for this command only, when you are its admin. Your active organisation is not changed. |\n\nThe version option is `--app-version` because `--version` prints the CLI's own\nversion.\n\n### `gamestage cdn ls`\n\n| Option | Type | Required | Default | What it does |\n| --- | --- | --- | --- | --- |\n| `--app <app>` | string | No | Every app | List only this app's files. |\n| `--org <id>` | string | No | Your organisation | List another organisation's files for this command only, when you are its admin. |\n\n### Addresses\n\nEvery file is at:\n\n```\nhttps://cdn.gamestage.ai/apps/<org>/<app>/<version>/<name>\n```\n\n`<org>` is your organisation's id. It comes from your workspace, so you cannot\npublish under another organisation's path.\n\n### File types\n\nThe name's extension decides the type the file is served with, and the file's\ncontents must match it.\n\n| Extension | Served as | Checked |\n| --- | --- | --- |\n| `.json` | `application/json` | Parses as JSON in UTF-8. |\n| `.html` | `text/html; charset=utf-8` | Is UTF-8. |\n| `.png` | `image/png` | Starts with the PNG signature. |\n| `.jpg`, `.jpeg` | `image/jpeg` | Starts with the JPEG signature. |\n| `.svg` | `image/svg+xml` | Is UTF-8 with an `<svg` element. |\n| `.webp` | `image/webp` | Starts with the WebP signature. |\n\n### What a fetch gets back\n\n| Header | Value |\n| --- | --- |\n| `Cache-Control` | `public, max-age=31536000, immutable` |\n| `Access-Control-Allow-Origin` | `*` |\n| `X-Content-Type-Options` | `nosniff` |\n\nThere is no firewall rule on the user agent, so a server-side fetcher such as\nStudio's gets the file like a browser does.\n\n### `--json` output\n\n`gamestage --json cdn put` prints `{ \"ok\": true, \"file\": { ... } }`, where\n`file` carries `org`, `app`, `version`, `name`, `key`, `url`, `contentType`,\n`size` and `sha256`. `gamestage --json cdn ls` prints `{ \"ok\": true, \"org\",\n\"origin\", \"files\": [ ... ] }`.\n\nA refusal prints `{ \"ok\": false, \"error\": { \"code\", \"message\" } }` and exits\n`1`. Success exits `0`.\n\n## When it refuses\n\n| Code | Why | What to do |\n| --- | --- | --- |\n| `file_exists` | That app and version already have a file with that name. | Publish under a new version with `--app-version`. |\n| `invalid_path` | The app, version or name is not one the host accepts, or the type is not on the list above. | Change it to match the rules in the reference. |\n| `type_mismatch` | The file's contents are not what its extension says. | Check the file, or rename it with the extension of what it is. |\n| `too_large` | The file is over 2 MB. | Make it smaller. For an image, compress it. |\n| `empty_file` | The file is empty. | Publish a file with something in it. |\n| `no_file` | The path is not a file. | Check the path. |\n| `not_org_admin` | Your workspace is not an admin of the organisation. | Ask a Monterosa operator to make your workspace an admin for it. |\n| `owner_only` | You are a member of the workspace, not its owner. | Ask the owner to run `gamestage cdn put`. |\n| `no_org` | Your workspace belongs to no organisation. | Ask a Monterosa operator to attach it to yours. |\n| `not_configured` | This Space does not host files. | Use the Space that serves cdn.gamestage.ai. |\n"}