Static Website Hosting on Azure Blob Storage

What is Static Website Hosting?

A static website consists of files that are served exactly as-is — HTML, CSS, JavaScript, images. There's no server-side processing, no database queries, no backend logic executed on the server. The browser downloads the files and runs everything client-side.

Modern frontend frameworks like React and Vue produce static builds — a folder of HTML, JS, and CSS files that can be served from any web server or object storage service like Azure Blob Storage.

Enabling Static Website Hosting

Via Azure Portal

1. Go to your Storage Account
2. In the left menu → Data management → Static website
3. Toggle to Enabled
4. Set Index document name → index.html
5. Set Error document path → 404.html (optional)
6. Click Save
7. Azure creates the $web container and shows you the endpoint URL

Via Azure CLI

az storage blob service-properties update \
  --account-name mystorageaccount2026 \
  --static-website \
  --index-document index.html \
  --404-document 404.html \
  --auth-mode login

The $web Container

When you enable static website hosting, Azure automatically creates a special container named $web. All website files must be uploaded to this container. The container is publicly readable — any file in $web can be accessed via the static website endpoint.

Deploying Your Website

# Build your frontend app first
# npm run build  (creates a /dist or /build folder)

# Upload all files to $web container
az storage blob upload-batch \
  --account-name mystorageaccount2026 \
  --destination '$web' \
  --source ./dist \
  --auth-mode login

# Set correct content types (important for JS/CSS)
# Azure CLI usually handles this automatically

# Delete old files not in the new build (clean deploy)
az storage blob upload-batch \
  --account-name mystorageaccount2026 \
  --destination '$web' \
  --source ./dist \
  --overwrite \
  --auth-mode login

The Static Website Endpoint

After enabling, your website is accessible at a URL like:

https://[accountname].z[N].web.core.windows.net

# Example:
https://mystorageaccount2026.z13.web.core.windows.net

Note: The zone number (z13, z30, etc.) depends on your region. This is different from the blob storage endpoint.

Custom Error Pages

Set a custom 404 page to handle requests for files that don't exist. This is particularly important for single-page applications (SPAs) where the router handles navigation — all routes should serve index.html.

Limitations

Blob static hosting has some important limitations:

• No custom domain with HTTPS out of the box — The default endpoint uses Azure's domain. Custom domain requires Azure CDN.
• No server-side logic — Only static files. No PHP, Node.js, Python. Use Azure Functions for APIs.
• No HTTP headers customisation — Can't add custom Cache-Control, CORS headers, etc. without CDN.
• No HTTP to HTTPS redirect — Requires CDN to enforce HTTPS.
• Single region — The storage account is in one region. Use CDN to add global distribution.

Adding CDN for Custom Domain + HTTPS

To use a custom domain (like www.yoursite.com) with HTTPS, you add Azure CDN in front of your static website:

1. Create an Azure CDN profile and endpoint pointing to your static website origin
2. Add your custom domain to the CDN endpoint
3. Enable HTTPS (free managed certificate from CDN)
4. Update your DNS to point to the CDN endpoint

See the Azure CDN with Storage page for the full setup guide.

Blob Hosting vs Azure Static Web Apps