CDN — file storage with public links and an own domain

• Essentials
• How CDNs work
• How to create a CDN?
• How to host a site on the CDN's own domain?
• CDNs API
• Troubleshooting
• What's next?

Essentials

• A CDN is a file storage in your flespi account with public access to the stored files.
• Each uploaded file gets a unique uuid and a public link https://cdn.flespi.io/file/{uuid}.
• Each CDN has its own domain in the flespi.app zone, for example https://a1b2c3d4e5f60718.flespi.app, where files uploaded with a path are served as a website.
• Typical uses are firmware for over-the-air updates, documents and media shared by link, and static pages or dashboards.

How CDNs work

• A file link is impossible to guess, and anyone who has it can download the file. The content type given at upload decides what a browser does with the file: image/png is shown, application/octet-stream is downloaded.
• The own domain is assigned when the CDN is created, does not change, and is shown in the domain field of the CDN.
• A file uploaded with a path is served by that path on the own domain. A path points to the latest file uploaded with it: the previous file keeps it in old_path.
• Files are kept until deleted. Upload a file with expires or auto_ttl to delete it automatically.
• Uploaded files are cacheable by default, so browsers may keep them without checking. A file uploaded with cacheable set to false is revalidated by its ETag on every request, use it for content that changes often.
• Public access to all files of a CDN, by links and on its domain, is controlled by the enabled flag and the ip_whitelist of IP address patterns.
• With a grant another subaccount can list the files of a CDN. Uploading and deleting files needs the edit access level.
• The storage size and traffic of each CDN are limited, see the platform restrictions in How flespi pricing works.

How to create a CDN?

1. Log in to the flespi panel.
2. Navigate to Storage -> CDNs and click the "+" button to add a new CDN. Give it a meaningful name and save.
3. Click the Upload button in the top right corner of the Files tab and pick a file. Right click on the uploaded file name and select the Copy link address item to get its link.

How to host a site on the CDN's own domain?

Upload each file of the site with its path through the CDNs API, one file per request, then open the domain of the CDN in a browser:

• A request for / or for a folder path ending with /, such as /docs/, is served by the index.html file of that folder, /index.html or /docs/index.html.
• Pages refer to each other by their paths, such as /css/style.css, the same way as on any web server.
• A path is plain text, not URL-encoded: the file with the path /my file.txt opens as /my%20file.txt. A path starts with / and cannot end with /, contain empty, . or .. segments, or the characters ? # * + \.
• To change a page, replace the content of its file. The file keeps its uuid and path.
• Uploading a new file with an existing path moves the path to the new file. Delete the previous files, which keep the path in old_path, with the filter exists('old_path').

CDNs API

To perform any operations with the CDNs and their files, use the CDNs API. For example, upload a file and get its link from the uuid in the result:

curl -X POST "https://flespi.io/storage/cdns/CDN_ID/files" \

  -H "Authorization: FlespiToken TOKEN" \

  -F "file=@firmware.bin;type=application/octet-stream"

Upload a page of the site with its path:

curl -X POST "https://flespi.io/storage/cdns/CDN_ID/files" \

  -H "Authorization: FlespiToken TOKEN" \

  -F 'data={"path": "/index.html"}' \

  -F "file=@index.html;type=text/html"

Read the domain of the CDN:

curl "https://flespi.io/storage/cdns/CDN_ID?fields=domain" \

  -H "Authorization: FlespiToken TOKEN"

Replace the content of a file, keeping its uuid and path. Set path to null here to remove the path:

curl -X PUT "https://flespi.io/storage/cdns/CDN_ID/files" \

  -H "Authorization: FlespiToken TOKEN" \

  -F 'data={"uuid": "FILE_UUID"}' \

  -F "file=@index.html;type=text/html"

Delete the files whose path was taken over by newer files:

curl -X DELETE "https://flespi.io/storage/cdns/CDN_ID/files" \

  -H "Authorization: FlespiToken TOKEN" \

  -d "{\"filter\": \"exists('old_path')\"}"

Troubleshooting

In case of any issues, check the Logs tab on the CDN screen: it records file uploads and replacements and the changes of the CDN size.

• A file link or a page on the domain answers 403 when the CDN is disabled, when the request comes from an IP address outside the ip_whitelist, or when the CDN is deleted.
• A page on the domain answers 404 when no file has its path. Check the exact path of the file, a request for a folder needs the trailing /.
• If a page shows outdated content after replacement, it was cached by the browser. Upload such files with cacheable set to false.
• If you accidentally deleted a CDN, you may restore it with all its files from the recycle bin within 30 days. It serves its files on the same domain again.

What's next?

• Deliver firmware to devices over the air, see How to upgrade my GPS tracker firmware OTA.
• Sign users in on a page hosted on the CDN's own domain, see How to add flespi login to your web page.
• Let an agent build, host and back the page for you, see flespi AI agents: apps and dashboards.