Skip to navigation

Hosting Static Sites and SPAs on Object Storage

A static site is a website made only of files — HTML, CSS, JavaScript, images — with no server code running for each visitor. A single-page app (SPA) built with React, Vue, Angular or Svelte is one too, once it’s built. You can host one on IBEE by uploading the built files to a bucket and putting the IBEE CDN in front of it for speed, HTTPS and your own domain. There’s no server for you to run or patch.

When to use this setup

Your site…Host it with
Is plain HTML, or a built React/Vue/Angular/Svelte app that calls APIsBucket + CDN (this page)
Renders pages on a server for each request (Next.js server mode, PHP, Django)A Cloud VM, optionally behind a load balancer
Is only images and downloads, without HTML pagesA bucket with a custom domain or the CDN

How it works

  1. You build the site into a folder that contains index.html.
  2. You upload that folder to a public bucket with the AWS CLI.
  3. A CDN distribution serves the bucket over HTTPS, caches files near users and, with Enable SPA, returns index.html for app routes like /dashboard. Your domain points to the CDN.

Before you begin

  • An IBEE organization with identity verification done. See Create an organization.

  • An S3 credential with Object Read & Write for the bucket, and its S3 Endpoint.

  • The AWS CLI version 2, set up with region auto and path-style addressing:

    aws configure set aws_access_key_id YOUR-ACCESS-KEY-ID --profile ibee
    aws configure set aws_secret_access_key YOUR-SECRET-ACCESS-KEY --profile ibee
    aws configure set region auto --profile ibee
    aws configure set s3.addressing_style path --profile ibee
  • Your site’s build output, and access to your domain’s DNS if you’ll use your own domain.

Host the site

1

Build the site

Run your framework’s production build. Upload the folder it produces:

FrameworkBuild commandOutput folder
React (Vite)npm run builddist/
React (Create React App)npm run buildbuild/
Next.js (static export, output: 'export' in next.config.js)npm run buildout/
Vue (Vite)npm run builddist/
Angularng build --configuration productiondist/PROJECT-NAME/browser/
SvelteKit (adapter-static)npm run buildbuild/
Plain HTML—Your site folder
2

Create a public bucket

Create a bucket, for example my-site (bucket names can’t contain dots). Then open Settings → General and turn on Public Access. Everything in this bucket will be readable by anyone, so keep only site files in it.

3

Upload the build

Replace my-site, WORKSPACE-ID and ./dist with your values. --delete removes files from the bucket that no longer exist in your build:

aws s3 sync ./dist s3://my-site/ --delete \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
4

Set cache headers on index.html

Hashed files such as assets/index-4f2a9c.js can be cached for a long time, but index.html must always be fresh so visitors get the latest version. Upload it again with no-cache, which tells browsers to check for a new copy each time:

aws s3 cp ./dist/index.html s3://my-site/index.html \
--cache-control "no-cache" --content-type "text/html" \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
5

Create a CDN distribution

Open Network & Security → CDN and click Create CDN. Choose Origin Type Object Storage Bucket, pick my-site, choose the Static Assets cache policy (1 year), and click Create Distribution. Note the CDN URL, such as dl-3f9c2a1b.cdn.ibee.ai. See CDN integration.

6

Turn on SPA routing (single-page apps)

On the distribution’s Overview tab, tick Enable SPA on the Single-page application (SPA) card and click Save. Routes such as /dashboard/settings then return index.html; requests for missing files still return 404. With the API: PUT /cdn/distributions/{distribution_id}/website-config (index_document, default index.html).

7

Add your domain

At your DNS provider, add a CNAME record from www (or another subdomain) to cname.cdn.ibee.ai. Then add www.example.com on the distribution’s page and click Verify. HTTPS is set up automatically once DNS resolves; DNS changes can take up to an hour. See CDN → Custom domains.

Verify

curl -I https://www.example.com/

You should see HTTP/2 200, content-type: text/html and cache-control: no-cache. For an SPA, also open a deep link such as https://www.example.com/about directly in the browser: it should load the app, not an error.

Redeploy

Each release is a build, a sync and a fresh index.html:

npm run build
aws s3 sync ./dist s3://my-site/ --delete \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
aws s3 cp ./dist/index.html s3://my-site/index.html \
--cache-control "no-cache" --content-type "text/html" \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee

Then purge /index.html on the distribution so the CDN fetches the new copy. It points to the new hashed file names, so the rest of the release loads fresh. Purge any other file you replaced under the same name, such as logo.png.

Limits and timing

Value
Static Assets cache time1 year
Short Cache cache time1 hour — an option if you redeploy often and don’t want to purge
index.htmlUpload with no-cache and purge it after each deploy
Custom domain DNSCan take up to an hour
Largest file in one upload5 GiB (the CLI uploads bigger files in parts)
Server-side codeNot supported — files only

Troubleshooting

You seeWhat it meansWhat to do
403 from the CDN URLThe bucket isn’t publicTurn on Public Access on the bucket.
The CDN URL works but your domain doesn’tDNS hasn’t updated, or the CNAME points at the bucket instead of the CDNdig www.example.com CNAME +short should print cname.cdn.ibee.ai.
404 when refreshing /dashboard or another app routeSPA routing is offTick Enable SPA, or switch the app to hash routing (/#/dashboard).
Visitors see the old site after a deployThe old index.html is still cachedPurge /index.html on the distribution, and make sure it was uploaded with --cache-control "no-cache".
The browser downloads the page instead of showing itindex.html has the wrong content typeUpload it with --content-type "text/html".
Mixed content warningsThe page loads http:// resourcesUse https:// for every script, image and API call.
CORS errors when the site calls an APIThe API doesn’t allow your site’s originAllow the site’s origin on that API, or on the bucket with CORS.
403 AccessDenied — Invalid region scope when uploadingThe CLI profile uses us-east-1Run aws configure set region auto --profile ibee.