Hosting a website does not require buying expensive web hosting packages or managing complex server software. If your project relies on simple HTML, CSS, JavaScript, and static media files, you can publish it completely free using modern cloud platforms.
Microsoft Azure provides a dedicated service called Azure Static Web Apps. This feature allows you to run static websites at zero cost while serving your pages through a fast global delivery network. When you link Azure to a GitHub repository, your site automatically updates whenever you push code updates.
In this detailed tutorial, you will learn how to host static website on azure from scratch. We will walk through preparing your GitHub repository, configuring your Azure web app, fixing automated workflow build errors, and mapping a custom domain with free SSL encryption.
Prerequisites for Hosting a Static Website on Azure
Before creating your web app, you need a few basic accounts and files ready. Gathering these prerequisites ahead of time makes the setup process simple and quick.
First, you need a Microsoft Azure account. Signing up is straightforward at portal.azure.com. New users can create an account using an existing email or Gmail address. Azure offers a perpetual free tier for static web hosting, meaning you can run hobby sites or personal projects without incurring monthly hosting bills.
Second, you need a GitHub account containing your static website files. Azure relies on GitHub to pull source code and manage deployments. Your site should consist of standard static files like HTML documents, CSS stylesheets, JavaScript files, and images.
Finally, if you want a professional brand address, you will need a custom domain name registered with a domain provider like Namecheap or GoDaddy. While Azure provides a free generated URL for every web app, connecting your own domain gives your project a clean and trustworthy identity.
Step 1: Preparing Your Source Code in GitHub
Azure Static Web Apps works directly with GitHub repositories to manage code and automate updates. Before touching settings in the Azure Portal, you must store your website files inside a repository.
Log into your GitHub account and create a new repository. You can choose either a public or private repository based on your privacy needs. Upload all your website files, ensuring your primary landing page is named index.html and sits in the root folder of the repository.
If your website includes multiple pages, stylesheet folders, or media files, maintain a clean folder structure. For example, keeping images in an images folder and stylesheets in a css folder keeps your repository readable and easy to maintain.
Once your code is pushed to GitHub, any future changes you make to your files will automatically trigger a deployment. Azure listens for changes in your repository branch and updates your live site within seconds.
Automating deployments through GitHub Actions ensures your live site updates instantly whenever you commit new code.
Step 2: Creating the Azure Static Web App Resource
With your repository ready, log into the Azure Portal to set up your web hosting environment. Azure streamlines resource creation through a simple configuration wizard.
In the top search bar of the Azure Portal, type ‘Static Web Apps’ and select the option from the search results. Click the Create button to begin configuring your new static app.
Select your Azure subscription and choose a Resource Group. If you do not have an existing resource group, click Create New and enter a descriptive name such as ‘web-app-group’. Resource groups organize related cloud services together so you can manage them easily.
Give your web app a unique name. Under the Hosting Plan section, choose the free tier designed for personal or hobby projects. This free tier allows you to host up to two static websites with full deployment features.
Select a deployment region close to your primary target audience, such as Central US or West Europe. Next, choose GitHub as your source control provider and click the authorization button to connect your GitHub account to Azure. Select your GitHub organization, repository name, and target branch.
Step 3: Fixing Common Deployment Errors in GitHub Workflows
After completing the setup wizard, Azure initializes the deployment process. However, raw HTML websites often trigger a deployment warning stating that no content was received from your site.
This issue occurs because Azure automatically creates a GitHub Actions workflow file designed for build frameworks like React or Next.js. Because pure HTML and CSS files do not require a build process, the workflow fails to locate compiled output files.
To fix this error, open your GitHub repository in a browser window and navigate to the .github/workflows directory. Click on the YAML configuration file created by Azure and select the edit icon.
Scroll down to the task section named Build and Deploy. Locate the line that specifies output_location. Directly beneath that line, hit enter and add the following configuration: skip_app_build: true. Ensure your indentation matches the surrounding YAML code.
Commit your changes directly to the main repository branch. This edit informs GitHub Actions that your project consists of static files and does not require compilation. GitHub will run the deployment pipeline again, and a green checkmark will confirm a successful site build.
Adding the skip_app_build flag prevents unnecessary compilation steps and fixes empty site errors on raw HTML projects.
Step 4: Configuring a Custom WWW Subdomain in Azure
While Azure provides a default domain name ending in .azurestaticapps.net, using your own domain name gives your site a polished finish. Adding a custom domain involves linking DNS records from your registrar to Azure.
Navigate to your Static Web App menu in the Azure Portal and click on Custom domains under the Settings sidebar. Click the Add button and select ‘Custom domain on other DNS’.
Type your full custom domain including the www prefix, such as www.easydomains.xyz. Click Next to view the CNAME record target generated by Azure. Copy the target string provided on the screen.
Log into your domain registrar dashboard, such as Namecheap. Locate the Advanced DNS or DNS Management panel for your domain. Click Add New Record and select CNAME Record from the dropdown menu.
Set the Host value to www and paste the Azure target string into the Value or Target field. Save your new DNS record. It can take between 5 to 15 minutes for new CNAME records to propagate globally across DNS servers.
Step 5: Setting Up Root Domain and TXT Verification
Visitors often type web addresses without entering www first. To make sure your site loads properly when someone enters your root domain name, you must configure root domain routing in Azure.
Return to the Custom domains menu in the Azure Portal and click Add again. Type your root domain name without any prefix, such as easydomains.xyz, and click Next.
Azure requires proof that you own the domain before activating root domain traffic. Select the option to generate a TXT verification code. Copy the alphanumeric code shown in the Azure validation wizard.
Go back to your domain registrar DNS management panel and create a new TXT record. Enter @ in the Host field to represent the root domain, and paste the verification code into the Value box. Save the record.
After saving the TXT record, create another CNAME or ALIAS record pointing @ to your Azure app URL. Return to Azure Portal and wait for validation to complete. Once DNS propagation finishes, Azure will display a green ‘Validated’ badge next to your root domain.
How SSL Provisioning and Security Work on Azure Static Web Apps
Security is essential for modern websites. Azure Static Web Apps automatically secures your custom domains by providing free SSL/TLS certificates.
Once your DNS records pass validation, Azure initiates automatic SSL certificate creation through Let’s Encrypt or Microsoft certificate authorities. You do not need to purchase separate SSL certificates or update encryption files manually.
When you first open your custom domain in a web browser, you might encounter a temporary privacy warning or security notice. This occurs because SSL certificate provisioning happens right after DNS validation finishes.
Allow 15 to 20 minutes for SSL activation to complete. You can read official details in the Azure Static Web Apps documentation. If your browser continues showing old cached pages, open an Incognito window or clear your local browser cache to view the fully secured HTTPS website.
Common Static Web App Mistakes and Troubleshooting
Setting up cloud hosting is straightforward, but beginner mistakes can lead to broken deployments or missing pages. Knowing how to diagnose common issues saves time.
One frequent mistake is misplacing the main HTML file. Your primary entry page must be named index.html and located in the top directory of your repository. If you place it inside subfolders without specifying search paths in Azure, the web app displays a blank page.
Another issue involves editing YAML workflow files with incorrect spacing. YAML configuration files rely on exact indentation. If you insert skip_app_build: true with incorrect indent alignment, GitHub Actions will report a syntax error during execution.
Finally, DNS propagation delay often confuses site owners. DNS changes do not happen instantly worldwide. To check whether your DNS records have updated properly, use online lookup utilities or test response times with a wordpress page speed and ttfb checker to evaluate live connection speeds.
DNS propagation and automatic SSL issuance require patience, as global edge servers take time to synchronize records.
Optimizing Your Azure Static Site for Better Traffic and Search Performance
Once your static site is active, you can introduce optimizations to improve performance, navigation, and discoverability.
Azure Static Web Apps supports custom routing and error handling through a configuration file named staticwebapp.config.json. Placing this file in your repository root allows you to define custom 404 error pages, redirect rules, and secure response headers.
To maximize search visibility, ensure your website structure follows search engine guidelines. Implementing clean URLs and providing structural governance files helps search crawlers index your pages effectively. You can use an online robots.txt generator to create rule files that guide web crawlers through your site structure cleanly.
Additionally, understanding modern web strategies like SEO vs AEO optimization strategies prepares your content for both traditional search engine indexing and AI-driven answer engines.
Conclusion
Hosting a static website on Microsoft Azure gives you professional-grade infrastructure at zero cost. By integrating GitHub repositories directly into Azure Static Web Apps, you establish an automated deployment pipeline that updates your live website every time you save new code.
With support for custom domain mapping, automatic SSL certificates, and global content delivery, Azure provides everything required to run personal tools, landing pages, or documentation sites reliably. Follow the steps in this guide to host static website on azure today.
Key Takeaways
- Azure Static Web Apps provides free hosting for up to two static websites on its hobby plan tier.
- GitHub integration enables automated continuous deployment whenever you push updates to your code repository.
- Adding skip_app_build: true to your GitHub workflow YAML file fixes deployment errors on raw HTML projects.
- Custom domains support both www and root domain addresses through CNAME and TXT record verification.
- Free SSL certificates are automatically issued and renewed by Azure once custom domains are validated.
Frequently Asked Questions
How can you host a static website for free on Microsoft Azure?
You can host static websites for free by using the Azure Static Web Apps service on its Free hosting plan. The process involves connecting a GitHub repository containing your static HTML, CSS, and JavaScript files directly to Azure. Azure then automatically builds and deploys your website whenever updates are pushed to GitHub.
How do you fix the ‘content not received’ deployment error in Azure Static Web Apps?
This issue typically occurs when the automatic workflow build fails to process the static files correctly. To resolve it, navigate to the `.github/workflows` folder in your GitHub repository and edit the workflow YAML file. Add the line `skip_app_build: true` directly under the `output_location` line in the build and deploy section, then commit the changes to trigger a clean deployment.
How do you add a custom domain to an Azure Static Web App?
To connect a custom domain, open the ‘Custom domains’ tab in your Azure Static Web App resource and enter your domain name. Next, log into your domain registrar (such as Namecheap) and create a CNAME record pointing your domain host to the Azure-provided site URL. For root domains, you must also generate and add a TXT record in your DNS settings to complete Azure’s ownership validation step.
