The simple plan

Before touching AWS, I sketched out the whole process.

The flow was simple:

1. Push an update from the local repo

2. GitHub Actions builds the site and pushes it to S3

3. CloudFront's cache gets invalidated, so it serves the new version

4. The user gets the update.

Building the boxes

Quick S3 bucket setup

The first step of this project is to create storage for the static files. Navigte to S3 > buckets > create buckets

I created my bucket with the following configurations:

• Bucket type: General purpose

• Bucket namespace: Global namespace

• Bucket name: myportfolio

• Block public access: [ticked]

• And the rest left at default settings

Note: The Amazon S3 bucket name must be globally unique across the AWS S3 namespace, not just unique within your AWS account or region.

CloudFront distribution configuration

To respond quickly and improve security, I set up CloudFront to handle content delivery and HTTPS.

For the origin, I pointed CloudFront at my S3 bucket, not the website endpoint. This setting enables OAC (origin access control), which lets CloudFront reach a private bucket without the bucket being public. I named the distribution and left the rest at their defaults

On the final create distribution page, CloudFront updated my S3 bucket's policy directly so it could restrict access to just this distribution. It required no manual copying, which was a nice surprise compared to what I expected going in.

Once the distribution finished deploying, I had a working .cloudfront.net URL, HTTPS by default, and now sitting in front of a bucket no one could reach directly.

The trust setup

Setting trust between GitHub and AWS

This is the first step for configuring the CI/CD pipeline. I used the OIDC provider type. Here, GitHub issues a short-lived identity token to a workflow while it's running. AWS is configured to trust the tokens issued by GitHub and check the token against a specific policy. If it matches, AWS sends back a temporary credential, which is valid for that one process.

To set this up;

1. Register GitHub as a trusted identity provider

2. Create an IAM role that only my GitHub-specific repo can access.

Head over to IAM > Identity provider > Add provider, and enter these details:

• Provider type: OIDC

• Provider URL: https://token.actions.githubusercontent.com

• Audience: sts.amazonaws.com

• Click Add provider

Proceed to create an IAM role. Head over to IAM > Roles > Create role

Set the trusted entity type to Custom trust policy and paste the following command in the box

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:YOUR_GITHUB_USERNAME/YOUR_REPO_NAME:ref:refs/heads/main"
        }
      }
    }
  ]
}

Edit fields like YOUR_ACCOUNT_ID and YOUR_GITHUB_USERNAME/YOUR_REPO_NAME to your personal AWS and GitHub information.

Click Next to go to the add permissions page.

On this page, click Create inline policy, and add the policy below to the policy box.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::YOUR_BUCKET", "arn:aws:s3:::YOUR_BUCKET/*"]
    },
    {
      "Effect": "Allow",
      "Action": "cloudfront:CreateInvalidation",
      "Resource": "arn:aws:cloudfront::YOUR_ACCOUNT_ID:distribution/YOUR_DISTRIBUTION_ID"
    }
  ]
}

Edit the fields YOUR_BUCKET and YOUR_ACCOUNT_ID to your personal AWS information

Proceed to name, review, and create the role.

Once the role is created, copy its ARN. This address goes into our workflow YAML file as the role-to-assume value. It tells GitHub Actions the role to request the temporary credentials for.

The GitHub Actions Workflow

This is the last piece of the project. In simple terms, this file does five things in this order:

• It pulls in my latest code

• Builds the site

• Authenticates to AWS using the OIDC (OpenID Connect) setup from the previous step

• Ships the built files to S3

• Clears CloudFront's cache so the new version is sent to the user

Proceed to create a .github/workflows/deploy.yml file and paste this code in.

name: Deploy static site
run-name: ${{ github.actor }} deployed "${{ github.event.head_commit.message }}"

on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build site
        run: npm run build   # adjust if your build script has a different name
 
      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::YOUR-AWS-ACCOUNT-ID:role/githubActionsPolicyDeploy   # replace with your role ARN
          aws-region: us-east-1   # adjust to your bucket's region
 
      - name: Sync site files to S3
        run: |
          # No separate build folder here — Tailwind just compiles output.css
          # in place, so we sync the whole project root, excluding anything
          # that isn't part of the actual deployed site.
          aws s3 sync . s3://YOUR-PROJECT-BUCKET\
            --delete \
            --exclude ".git/*" \
            --exclude ".github/*" \
            --exclude "node_modules/*" \
            --exclude "input.css" \
            --exclude "package.json" \
            --exclude "package-lock.json" \
            --exclude "tailwind.config.js" \
            --exclude "README.md" \
            --cache-control "public, max-age=31536000, immutable" \
            --exclude "index.html"
 
          # index.html should not be cached long, so browsers pick up new deploys quickly
          aws s3 cp ./index.html s3://login-form-frontend/index.html \
            --cache-control "public, max-age=0, must-revalidate"
 
      - name: Invalidate CloudFront cache
        run: |
          aws cloudfront create-invalidation \
            --distribution-id YOUR-DISTRIBUTION-ID\
            --paths "/*"
 

Update all fields in ALL CAPS with your AWS information.

Once the YAML file has been pasted;

• Commit and push to main.

• Watch the Actions tab in your GitHub repo; each step shows live status (yellow for running, green for passed, red for failed).

• On success, visit your CloudFront URL and hard-refresh to confirm the change is live.

• You can make a small change, push again, and confirm it deploys automatically. This proves the pipeline works end to end.

The bugs

Default root was empty

Once the distribution finished deploying, I opened the .cloudfront.net URL, expecting my homepage. Instead, I got this error message.

My first thought was permissions. Maybe the bucket policy CloudFront had written wasn't correct. I checked, and nothing about the setup looked wrong on paper.

The real problem came from CloudFront's general settings. When the client hits the URL, CloudFront needs to know which specific file to serve. Without the setting, CloudFront asks S3 for the root path itself, which is treated like a request to list the bucket's content. This request required a different permission (s3:ListBucket) than the one my policy actually granted (s3:GetObject). So instead of a clear "file not found," I got an "Access Denied" error.

The fix was quite simple. I set "Default root object" to index.html in the distribution's general settings.

Not authorized to perform AssumeRoleWithWebIdentity error

After fixing the default root error, I pushed again, expecting things to work. Instead, I got a new error in the "Configure AWS credentials" step.

Error: Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity

From the error GitHub Actions returned, I figured the error had something to do with the IAM role's trust setup. I checked them one by one; the account ID matched, the audience matched, the branch name matched, and everything looked correct.

I compared the trust relationship against my repo's actual URL, letter by letter, and found it: one letter in my repo name was lowercase in the policy where it should have been uppercase. It turns out the condition matching GitHub's identity token is case-sensitive.

I fixed the error, pushed again, and this time, the credentials step passed.

Small projects, real lessons

Setting up cloud resources is, in itself, real progress in cloud engineering. Here, I set up a static frontend with a CI/CD pipeline, ran into real errors along the way, and worked through each one.

From here, you can take it further by setting up a real domain, with an ACM certificate attached to CloudFront via Route 53. It's a natural next step on top of everything in place.

Imagine you have a group of friends who test Ethereum protocols. The group members get faucets manually, where the admin sends sepolia ETH to addresses, one at a time. This process is stressful and takes a lot of time. Luckily, there’s a way to solve this problem by building a faucet.

This article explains how to build a simple sepolia faucet, write scripts and deploy on sepolia. The audience is expected to have basic solidity knowledge, and WSL commands.

Setting Up the Project

Foundry does not work natively on Windows Powershell. Instead, install WSL (windows subsystem for Linux) with the following steps:

1. Open Windows Powershell.

2. Run the command below:

wsl --install

3. Once the download is complete, head over to VS code

4. Click the button at the bottom left corner to open a remote connection and connect to WSL.

5. Open the WSL terminal in VS code and type the command below to install foundry.

curl -L https://foundry.paradigm.xyz | bash
foundryup

6. Create and enter a folder using the command below:

mkdir TestFaucet
cd TestFaucet
forge init

The forge init command initializes a Foundry project in your folder, sets up the structure and configuration needed to write, test, and deploy smart contracts.

Your folder should look like this

Building the Faucet

To build the faucet, we will use the Solidity language. To get started:

1. Open the src folder in the TestFaucet folder

2. Create a file named Faucet.sol

Note: If your VS code is not familiar with the solidity language, head over to VS code extensions and download the “Solidity by Juan Blanco” extension.

In the Faucet.sol file, type the code below:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.29;

• The first line is a license identifier, that tells tools and users which license the contract code is published. This is required by the Solidity compiler (as of Solidity 0.6.8+) to avoid warnings.

• The second line indicates the contract is meant to be written in and compiled with Solidity 0.8.29.

We define a contract named Faucet

contract Faucet {

}

In the defined contract Faucet, initialize some state variables. State variables are parameters that are declared inside a contract but outside of functions. They are permanently stored on the blockchain. Initialize some state variables with the code below:

    address public owner;
    uint256 public constant MAX_AMOUNT = 0.2 ether;
    mapping(address => uint) public lastClaimedAt;
    mapping(address => bool) public whitelisted;

The code above:

• Creates an owner variable with the data type of address.

• Declares a constant 256-bit unsigned integer named MAX_AMOUNT set to 0.2 ether.

• Creates a mapping named lastClaimedAt that maps addresses to uint values.

• Creates a mapping named whitelisted that maps addresses to boolean values.

In the Faucet contract, initialize the following events below:

    event Whitelisted(address indexed user);
    event RemovedFromWhitelist(address indexed user);
    event Claimed(address indexed user, uint256 amount);

Events are log entries that are recorded on the blockchain. They are used for communication between your contract and external consumers, like user interfaces, in a cost-efficient way.

The code above creates an event for when a user is whitelisted, removed from the whitelist, and when a user has claimed faucet.

After creating an event, define ownership of the contract using a constructor:

constructor() {
        owner = msg.sender;
    }

Constructors in solidity are special functions that run only once, during deployment. In the code above, we set the owner of the contract to the address of the deployer msg.sender. This would help to provide security features on some functions in our contract.

Moving on from constructors, create needed modifiers.

    modifier onlyWhitelisted() {
        require(whitelisted[msg.sender], "Not whitelisted");
        _;
    }

    modifier onlyOwner() {
        require(msg.sender == owner, "only owner can call this function");
        _;
    }

Modifiers are special keywords in solidity, which is used to change the behaviour of functions. Modifiers are placed beside functions and used for access control, input validation, or reusable pre-checks before a function runs. In this code we use the following modifiers:

• onlyWhitelisted - To check if msg.sender is whitelisted.

• onlyOwner - To check if msg.sender is the owner of the contract.

Proceed to create the necessary functions

    function addToWhitelist(address user) external onlyOwner {
        require(!whitelisted[user], "Address already whitelisted");
        whitelisted[user] = true;
        emit Whitelisted(user);
    }

    function removeFromWhitelist(address user) external onlyOwner {
        require(whitelisted[user], "Address not whitelisted");
        whitelisted[user] = false;
        emit RemovedFromWhitelist(user);
    }

    function claim() external onlyWhitelisted {
        require(
            block.timestamp >= lastClaimedAt[msg.sender] + 2 days,
            "Claim cooldown: wait for 2 days"
        );

        uint payout = address(this).balance >= MAX_AMOUNT
            ? MAX_AMOUNT
            : address(this).balance;
        require(payout > 0, "Faucet is empty");
        lastClaimedAt[msg.sender] = block.timestamp;
        payable(msg.sender).transfer(payout);
        emit Claimed(msg.sender, payout);
    }

    function drainFaucet() external onlyOwner {
        uint256 balance = address(this).balance;
        require(balance > 0, "No faucet to drain");

        payable(owner).transfer(balance);
    }

There are four main functions for this Faucet:

• addToWhitelist() - This function can only be called by the owner of the contract. This function:

  1. Takes in input of address data type

  2. Checks if the address has not been whitelisted.

  3. Whitelist the address

  4. Sends out a success message

• removeFromWhitelist() - This function can only be called by the owner of the contract. This function:

  1. Takes in input of address data type

  2. Checks if the address has been whitelisted.

  3. removes the address from whitelist

  4. Sends out a success message

• claim() - This function can only be called by whitelisted addresses. This function:

  1. Checks if the last claim of the whitelisted address is less than 2 days

  2. Checks if the faucet is empty, returns a faucet is empty message if its empty

  3. Saves the time where the address last claimed.

  4. Sends sepolia faucet to eligible address.

  5. Emits a success message which could be used off-chain.

• drainFaucet() - This function can only be called by the owner of the contract. This function:

  1. Checks if the faucet balance is empty

  2. Sends all the faucet balance to the owner if its not empty

Lastly, to enable the contract receive ETH, we set a special fallback function in the contract

receive() external payable {}

Deploy the Faucet to Sepolia

To deploy our contract to sepolia, we need the following:

1. An RPC endpoint

   • A node provider like Infura, Alchemy, or Ankr. We will use Alchemy in this example.

2. An encrypted private key

   • This will be used to sign and send the deployment transaction.

   • For safe practice, we will encrypt the key.

3. A deploy script written in Solidity

   • Uses Foundry's forge-std/Script.sol

   • This script will handle contract deployment logic

4. Sepolia ETH

   • The private key must control an account with sepolia ETH.

To create an RPC endpoint;

1. Sign Up / Log In to Alchemy

Go to Alchemy website

• Click Sign Up (or Log In if you already have an account)

2. Create a New App

• Once logged in, go to your Alchemy dashboard

• Click “+ Create App”

• Fill in the form:

  • Name: e.g., SepoliaTestApp

  • Description: e.g., Create a Faucet

  • UseCase: Other project

• Click Next

• Click Ethereum

• Click Next

• Click “Create App”

3. Get the RPC Endpoint

1. After the app is created, go to the app's Details page

2. Under “API Key”, you'll see the HTTPS endpoint

   • Switch the dropdown from mainnet to sepolia

   • It looks like:

       https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
     

3. Copy this URL — it's your RPC endpoint

4. Use in Foundry

In foundry.toml, save your endpoints :

[rpc_endpoints]
sepolia = "https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY"

Private key encryption is the best practice when working in web3 development. Saving your keys in the .env file is very unsafe and is risky especially when pushing your code to github. To encrypt your private key in foundry;

Run this command in your WSL terminal

cast wallet import defaultKey --interactive //The name of your private key is set to "defaultKey"

The terminal prompts you to enter the following

1. Your private key

2. A new password

Note: As you type your private key and password, the terminal does not display any characters. This is a security feature to protect sensitive information. Please proceed.

Once this has been completed, the terminal logs a success message

Deployment Script

Writing a deploy script automates the deployment of your smart contract to a blockchain using your wallet and an RPC provider. The deployment code is below:

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.29;

import {Script} from "forge-std/Script.sol";
import {ApexFaucet} from "../src/ApexFaucet.sol";

contract DeployApexFaucet is Script {
    function run() external returns (ApexFaucet) {
        vm.startBroadcast();
        ApexFaucet apexFaucet = new ApexFaucet();
        vm.stopBroadcast();
        return apexFaucet;
    }
}

The code above basically starts a broadcast to the rpc node to deploy a new instance of your contract on sepolia.

To deploy the contract using the script, run the command below;

forge script script/DeployApexFaucet.s.sol:DeployApexFaucet --rpc-url sepolia --private-key defaultKey --broadcast

The command above;

• Compiles the script script/DeployApexFaucet.s.sol

• Connects to sepolia using the --rpc-url sepolia

• Signs the transaction with our --private-key defaultKey

• Uses the --broadcast to send transactions on the sepolia network

Once your contract has been deployed, proceed to fund the contract using the contract address

Conclusion

In this article, we learnt how to build and deploy a faucet contract to the sepolia testnet. We covered the entire process from setting up the Foundry development environment to writing the smart contract, testing its functionality, and deploying it to the Sepolia testnet.

After building this project, you can take a step further to build a frontend, where users interact to claim faucet, log error messages like “not eligible” for ineligible participants, and also perform gas optimization techniques to reduce the amount of gas used.