Forem: Piotr Popiolek

How AWS Lightsail Limit Forced Us to Rethink Our Lab Infrastructure

Piotr Popiolek — Wed, 10 Dec 2025 21:26:44 +0000

During a recent preparation to hands-on lab we ran into a surprising limit: AWS Lightsail Container Service only allows 4 custom domains per account. We needed a separate public instance of our application for each lab participant (we predicted 11 participants), so this quota was a deal-breaker for the container service approach. And we discovered that like one day before the actual lab starts, so we had to act quickly.

This post describes the practical solution we adopted: run a single Lightsail (Ubuntu) instance, host multiple app containers there with docker-compose, and expose each container under its own subdomain via a Cloudflare Tunnel. The result: fast deployment, one public IP-less server, and stable per-user URLs.

TL;DR

Problem: Lightsail Container Service limits custom domains to 4 → can't create per-user public URLs.
Solution: Use a Lightsail Instance (Ubuntu) + docker-compose to run multiple containers and Cloudflare Tunnel to map subdomains to localhost ports.
Result: 11 public subdomains served from one instance without exposing ports or a fixed public IP in DNS.

Why This Architecture?

Running a Lightsail Instance Virtual Machine gives full control and no custom-domain quota.
docker-compose is simple to orchestrate many containers on one host.
Cloudflare Tunnel provides secure inbound connectivity without opening firewall ports or relying on a static IP: cloudflared accepts connections for specified hostnames and forwards traffic to local services.

Architecture (simple view):

app1.lab.work → cloudflared (tunnel) → localhost:5001 → our-app-1 (container)
app2.lab.work → cloudflared (tunnel) → localhost:5002 → our-app-2 (container)
...
app11.lab.work → cloudflared → localhost:5011 → our-app-11

Example docker-compose

This is the lightweight pattern we used. Each service runs the same application image but uses a distinct container name and public-mapped port.

version: "3.8"
services:
  our-app-1:
    build: ./our-app
    container_name: our-app-1
    ports:
      - "5001:5001"
    environment:
      - PORT=5001
    restart: unless-stopped

  our-app-2:
    build: ./our-app
    container_name: our-app-2
    ports:
      - "5002:5001"
    environment:
      - PORT=5001
    restart: unless-stopped

  # ...
  our-app-11:
    build: ./our-app
    container_name: our-app-11
    ports:
      - "5011:5001"
    environment:
      - PORT=5001
    restart: unless-stopped

Notes:

The containers all expose the application on the container's internal port 5001, but we map distinct host ports (5001..5011) so cloudflared can forward to the correct service.
If your app can read PORT from env, adjust container start command so it binds to the correct port (we used the same internal port and mapped different external ports).

deploy.sh (what we actually used)

Below is the deploy script we executed on the Lightsail instance (/home/ubuntu/lab). The script installs Docker and cloudflared, builds the containers, writes a Cloudflare tunnel config, and starts the cloudflared service. Important: the script writes a config that references /etc/cloudflared/lab.json (the tunnel credentials file). Creating that credentials file requires a one-time cloudflared "tunnel create" step which is explained further below.

#!/bin/bash
set -e

echo "[1/5] Installing Docker & Cloudflared..."
sudo apt update
sudo apt install -y docker.io docker-compose wget

# Install cloudflared
wget -O cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb || sudo apt --fix-broken install -y

echo "[2/5] Building 11 app containers..."
cd /home/ubuntu/lab
sudo docker-compose build

echo "[3/5] Starting containers..."
sudo docker-compose up -d

echo "[4/5] Setting up Cloudflare tunnel config..."
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml > /dev/null <<EOF
tunnel: lab
credentials-file: /etc/cloudflared/lab.json
ingress:
  - hostname: app1.lab.work
    service: http://localhost:5001
  - hostname: app2.lab.work
    service: http://localhost:5002
  - hostname: app3.lab.work
    service: http://localhost:5003
  - hostname: app4.lab.work
    service: http://localhost:5004
  - hostname: app5.lab.work
    service: http://localhost:5005
  - hostname: app6.lab.work
    service: http://localhost:5006
  - hostname: app7.lab.work
    service: http://localhost:5007
  - hostname: app8.lab.work
    service: http://localhost:5008
  - hostname: app9.lab.work
    service: http://localhost:5009
  - hostname: app10.lab.work
    service: http://localhost:5010
  - hostname: app11.lab.work
    service: http://localhost:5011
  - service: http_status:404
EOF

echo "[5/5] Starting Cloudflare tunnel..."
sudo systemctl daemon-reload
sudo systemctl enable cloudflared
sudo systemctl restart cloudflared

echo "=============================="
echo " Your our apps are ready!"
echo "=============================="
echo ""
echo "Public URLs:"
for i in {1..11}
do
  echo "app$i → https://app$i.lab.work"
done

Important: the credentials-file: /etc/cloudflared/lab.json value must point to an actual tunnel credentials JSON file created when you run cloudflared tunnel create lab (covered next). If no credentials-file is present, cloudflared service will fail to start.

One-time Cloudflare Tunnel Steps (interactive)

Install cloudflared locally or on the server (we installed on server in the script).
Login and create the tunnel (this requires access to the Cloudflare account for the lab.work zone):
- Run: cloudflared login
  - This opens a browser to authenticate your Cloudflare account and grants the cloudflared instance permissions to make DNS records.
- Then create the named tunnel:
  - cloudflared tunnel create lab
  - This creates a credentials file at ~/.cloudflared/<TUNNEL-ID>.json.
- Copy the credentials file to /etc/cloudflared/lab.json:
  - sudo mkdir -p /etc/cloudflared
  - sudo cp ~/.cloudflared/<TUNNEL-ID>.json /etc/cloudflared/lab.json
Create DNS routes for each hostname (you can also create DNS records in the Cloudflare dashboard):
- For each hostname run:
  - cloudflared tunnel route dns lab app1.lab.work
  - cloudflared tunnel route dns lab app2.lab.work
  - ...
- This creates Cloudflare DNS records that point the hostnames to the tunnel. You should see them as proxied A/CNAME records in Cloudflare DNS.
Start the tunnel (the deploy script starts the cloudflared system service):
- Check logs: sudo journalctl -u cloudflared -f
- Test: curl or open https://app1.lab.work

Notes:

If you prefer to manage DNS manually in the Cloudflare UI, create proxied A or CNAME records for each subdomain pointing to the tunnel as instructed by the Cloudflare docs. Using cloudflared tunnel route dns is convenient because it automates DNS creation.
The login + tunnel creation step is interactive. For fully automated setups, Cloudflare API tokens and non-interactive flows can be used, but that requires careful management of keys.

Caveats, Security & Gotchas

The Lightsail Instance is a single point of failure. Please note that this setup was created specifically only for lab/trainings. For higher availability, run multiple instances behind a load balancer or use Kubernetes/ECS.
The tunnel credentials JSON must be stored securely (we place it in /etc/cloudflared and restrict file permissions).
Rate-limits / fair-use: Cloudflare Tunnel is intended for this type of workload, but verify any usage limits for your plan, and ensure you don’t hit Cloudflare or upstream rate-limits during peak lab use.
DNS propagation: After tunnel route dns there can be short DNS propagation delays.
Exposed ports: We never open inbound ports on the VM for the apps — cloudflared handles inbound traffic via the tunnel. You should still harden SSH and instance access.
Logs & debugging: check sudo journalctl -u cloudflared -f and docker logs <container> when things misbehave.
TLS: Cloudflare provides TLS for your hostnames automatically when using the tunnel and proxied DNS records.

Improvements & Alternatives

Traefik or nginx as an internal reverse-proxy: run one proxy on host that routes subdomains to containers, then point Cloudflare Tunnel to the proxy (single local port). This reduces the number of host ports and centralizes routing logic (and makes scaling containers more flexible).
Use a wildcard subdomain and generate DNS records programmatically if many labs are expected; Cloudflare supports automation via API tokens.
If you need thousands of per-user instances, move to container orchestration (k8s, ECS) and either use an Ingress controller + external LB or scale with multi-instance / autoscaling groups.
Consider ephemeral user environments that spin up and down on-demand to save cost.
Monitoring and health checks: add health endpoints and simple monitors to restart broken containers automatically.

Cost & operational note

Lightsail Instances are cheap and predictable - Instance with 2 GB Memory, 2 vCPUs, and 3 TB Transfer was enough for us (it costs 12$/month)
Cloudflare Tunnel is free for many small-use cases, we had a domain there but we did not pay anything for our two-days heavy usage.

Conclusion

Switching from Lightsail Container Service to a Lightsail Instance + docker-compose + Cloudflare Tunnel gave us:

Fast, repeatable lab deployments on a single server
Individual public subdomains per participant
A secure inbound setup without opening host ports
..And it really saved us and we did not have to cancel the event in the last minute. :)

From Frustration to Automation: Building a Squash Court Availability App

Piotr Popiolek — Thu, 23 Oct 2025 20:14:28 +0000

Introduction

A few months back, I wanted to reserve a squash court, as usual, on a Wednesday evening. Unfortunately, everything was booked in my favorite club, so I started looking for other places. I was on my phone, which wasn’t very convenient, and every website was different — so I quickly got frustrated.

This situation happened a few times, and then I realized I could make this task easier by creating a small app to check court availability for me. It seemed like a good small project. I have two small kids, so I don’t have much free time, but I decided to spend 15–30 minutes on it whenever I could — and here we are!

What started as a quick idea to save a few clicks, turned into a mini project — a Python + FastAPI app hosted on AWS Lightsail, with full GitHub Actions automation.
In this post, I will share how I built it, automated deployment with CI/CD, and what I learned along the way.

Architecture

During my IT career, I spent over 10 years as an Infrastructure Engineer and the next 5 as a DevOps Engineer, so I’m not really a programmer. That’s why my technical choices were mostly about simplicity rather than software design perfection.

As I mentioned, time wasn’t on my side, so I decided on a simple architecture. Still, I wanted to learn something new, so I promised myself to use at least one AWS service I hadn’t worked with before.
The choice fell on AWS Lightsail.

Amazon Lightsail offers easy-to-use virtual private servers (VPS), containers, storage, and databases. It’s really intuitive and fits perfectly for my small app.

I’m quite comfortable with Python, so the backend is built with FastAPI. For the frontend, I used some simple HTML and CSS - generated mostly by ChatGPT, since I don’t have strong frontend experience.

To parse the web pages, I used the BeautifulSoup module, which provides methods and Pythonic idioms to navigate, search, and modify the parsed HTML tree.

Tests are based on pytest and mock, with simple assertions for specific use cases.

The code is hosted on GitHub, and I use GitHub Actions to build, test, and deploy automatically to AWS Lightsail after every push to the main branch.

Here’s how the overall architecture looks:

Initial app design

The main goal was to create a lightweight, intuitive web page to check squash court availability in Wroclaw.
The user can choose a date from the calendar (up to one week ahead) and select an hour between 06:00 and 23:00 (full hours only, since most facilities don’t support half-hour bookings).

After selecting the date and hour, the user clicks “Sprawdz” (means Search), and all sports facilities are listed with availability information. For the biggest club, Hasta La Vista, the app also lists individual courts — since there are 32 of them and players often prefer specific ones.

How to pull the data?!

Once I knew what I wanted to achieve, I started figuring out how to do it.
First, I gathered all sports facilities in Wroclaw that offer squash. Then, one by one, I tried to fetch the data I needed. Tools like curl and browser dev tools helped a lot.

After a few experiments, I wrote my first Python file — hasta.py. Using requests and BeautifulSoup, I fetched each website’s HTML and parsed the structure based on date and time. It looked like follow:

def check_availability(date_str: str, time_str: str):
    url = f"https://(...)"
    datetime_variants = [
        f"{date_str} {time_str}:00",
        f"{date_str}T{time_str}:00"
    ]
    try:
        resp = requests.get(url, timeout=10)
        resp.raise_for_status()
        data = resp.json()

        if "html" not in data:
            return "❌ Failed to fetch calendar data."

        soup = BeautifulSoup(data["html"], "html.parser")
        all_elements = soup.select("[data-begin]")

        for el in all_elements:
            data_begin = el.get("data-begin")
            if data_begin in datetime_variants:
                text = el.get_text(strip=True)
                if "Book" in text:
                    return (
                        f"✅ Court is available {date_str}  {time_str}"
                        )
                elif "Notify me" in text:
                    return f"❌ Court is not available  ({time_str})  {date_str}"

After a few evenings, I had an early version of a crawler that could check court availability for all clubs in the city.
In the meantime, I also started working on a simple frontend to connect the crawler with a web interface — again, as I have already mentioned, mostly with ChatGPT’s help.

The frontend consists of three main files: style.css, index.html, and result.html.
Everything was working well locally, so I decided to deploy it as a container on AWS Lightsail.

Let's Automate A Few Things

Before deploying anything manually to AWS, I wanted to automate the process as much as possible.
Since the code was already on GitHub, GitHub Actions was a natural choice for CI/CD. I decided to build a simple pipeline that would:

Build the Docker image
Run tests using pytest
Deploy automatically to AWS Lightsail

I also decided to use OIDC (OpenID Connect) for authentication between GitHub and AWS, so I didn’t need to store long-lived access keys (you can check on OIDC Stack in my previous blog post regarding AWS Serverless). This approach is more secure and follows AWS best practices for CI/CD integration.

Here’s a simplified version of the GitHub Actions workflow:

- name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT }}:role/github-actions-role
          aws-region: eu-west-1

      - name: Build Docker image
        run: docker build -t court-checker .

      - name: Install lightsailctl
        run: |
          curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-amd64/lightsailctl" -o "/usr/local/bin/lightsailctl"
          chmod +x /usr/local/bin/lightsailctl
          /usr/local/bin/lightsailctl --version

      - name: Create Lightsail container service if not exists
        run: |
            set -e
            if ! aws lightsail get-container-services --service-name court-checker >/dev/null 2>&1; then
              echo "Creating Lightsail container service..."
              aws lightsail create-container-service \
                --service-name court-checker \
                --power medium \
                --scale 1
            else
              echo "Lightsail container service already exists."
            fi      

      - name: Push image to Lightsail registry
        id: push
        run: |
          set -euo pipefail
          OUTPUT=$(aws lightsail push-container-image \
            --service-name court-checker \
            --label web \
            --image court-checker:latest)

          echo "$OUTPUT"

          # Extract registryPath from human-readable output
          REGISTRY_PATH=$(echo "$OUTPUT" | grep -oE ':court-checker\.web\.[0-9]+' | head -n 1)

          if [ -z "$REGISTRY_PATH" ]; then
            echo "ERROR: No registryPath found in push output."
            exit 1
          fi
          echo "registry_path=$REGISTRY_PATH" >> $GITHUB_OUTPUT
          echo "Using image: $REGISTRY_PATH"

      - name: Create container config
        run: |
          set -euo pipefail
          cat > container.json <<EOF
          {
            "web": {
              "image": "${{ steps.push.outputs.registry_path }}",
              "ports": {
                "8000": "HTTP"
              }
            }
          }
          EOF
          cat container.json

      - name: Create endpoint config
        run: |
          echo '{
            "containerName": "web",
            "containerPort": 8000,
            "healthCheck": {
              "path": "/health",
              "successCodes": "200-499",
              "timeoutSeconds": 5,
              "intervalSeconds": 10,
              "healthyThreshold": 2,
              "unhealthyThreshold": 2
            }
          }' > endpoint.json

      - name: Deploy to Lightsail
        run: |
          aws lightsail create-container-service-deployment \
            --service-name court-checker \
            --containers file://container.json \
            --public-endpoint file://endpoint.json

Release And Share With Others

Once all tests were done and I had used the app myself for a couple of days, I decided to share it with a few of my friends.
They tried it for about a week, gave me some feedback, I fixed a few things, and then decided to share it with a wider group.

Squash isn’t super popular, but I posted about the app in a local Facebook group with around 3,000 squash enthusiasts from Wroclaw so they could give it a try.
Now I can see there are around 20–50 visits per week — which makes me really happy that at least some people are finding it useful!

Costs

Obviously, I wanted to keep costs as low as possible. Fortunately, I’m an AWS Community Builder, so I have some AWS credits, which gave me flexibility in initial testing and I did not need to bother too much about that.
Here’s the rough cost breakdown:

Domain registration: around $45 for three years + $10 tax (one-time cost)
AWS Lightsail container (micro tier: 0.25 vCPU, 1GB RAM): $10/month
Each container service includes 500 GB/month data transfer. Extra data costs start at $0.09/GB depending on the region.
GitHub Actions: 2,000 free minutes per month (my project used only 103 minutes in August)

Thoughts about AWS Lightsail?

It’s definitely a great and easy way to deploy small web apps with minimal effort.
You get a public DNS by default:
https://<app-name>.<random_digits>.<region>.cs.amazonlightsail.com

Containers are perfect for small/medium projects or proof-of-concepts. I didn’t use instances, but they seem suitable for larger workloads.

With GitHub Actions automation, I don’t need to worry about deployment — it happens automatically after every push.
The only downsides I’ve noticed are:

Lack of container-level alarms and metrics (available only for instances)
Occasional delays during deployment

Overall, it’s a neat and simple setup for quick and cost-effective deployments.

Conclusion And Key Takeaways

Looking back, this small side project turned out to be much more than I expected.
What started as a simple idea to save time booking a squash court became a fun way to learn, automate, and explore new AWS services. I truly recommend that everyone try something like this and not be afraid to experiment.
I also realized how much can be achieved by dedicating just a little time each day — consistency really does beat intensity.
Here are also a few takeaways I’d like to share as a summary:

Start small, iterate often: Even with just 15–30 minutes a day, you can deliver a working project over time.
AWS Lightsail is underrated: It’s perfect for small, containerized apps — simple setup, predictable cost, and built-in DNS.
Automation saves time: GitHub Actions makes it easy to build, test, and deploy without manual steps or AWS Console clicks.
Security by design: Using OIDC between GitHub and AWS avoids storing long-lived credentials.
Don’t fear imperfect tools: FastAPI, BeautifulSoup, and a bit of ChatGPT-generated frontend were enough to get a solid MVP online.

And if you’d like to take a look at the app yourself, check it out here! It is in Polish however should be intuitive for everyone.

AWS Serverless hands on part 2/2

Piotr Popiolek — Tue, 11 Feb 2025 07:47:30 +0000

At the beginning, I would like to emphasize that this is the second part of our journey. Please read First Part before you move forward!

Short Intro

I hope you took some time after reading the first part, and now we are ready to continue! We have already learnt about some serverless services and architecture of what we want to achieve. We also know what are our main assumptions and which technology we want to use. Our next step will be to get familiar with the scope of application and details about backend and frontend.

Application Description

Coming up with an idea for this application was the most challenging part for me. I didn’t want to simply display an index.html file with "Hello World," but I also struggled to think of a more complex use case. Since I wanted to implement CRUD (Create, Read, Update, Delete) functionality, I decided to use DynamoDB as the database and focus on GET/POST endpoints.

Eventually, the idea I settled on may not be the most sophisticated, but it serves its purpose well as a hands-on project.

Our serverless application functions as a kind of guest book. It is hosted on CloudFront with static content stored in S3. The application offers two main options:

"Add Data" – Allows users to submit information
"Fetch Data From Backend" – Retrieves stored data based on user input

Behind the scenes, we have API Gateway with GET and POST endpoints handling the requests. When a user clicks on "Add Data", they are prompted to answer a few mandatory questions: City, Name, and Year of Birth. The City serves as the partition key in DynamoDB.

To retrieve stored data, users click "Fetch Data From Backend", enter a City, and receive all records associated with that city from the database.

The application in the web browser looks as follow:

Data Storage and Directory Structure
Every value entered into the application is recorded in DynamoDB. In the following sections, we will dive into the details of how the various services work and how they are connected in our setup.

For now, let's take a look at the Directory Structure. The CDK (Cloud Development Kit) is already initialized, and the tests, stacks, and GitHub workflow are pre-configured. Below is the directory structure:

A brief overview of each folder:
.github/worfkflow - Defines our pipeline for deploying stacks
deploy/cdk/bin - The entry point for CDK with defined stacks
deploy/cdk/lib - Contains the main CDK constructs
deploy/cdk/frontend - Holds the frontend files for our page
deploy/cdk/lambda - includes the Lambda function which is triggered by API Gateway
deploy/cdk/test - Contains test files for CDK
deploy/cdk/{cdk.json,package.json,package-lock.json,jest.config.js} - npm/CDK configuration files

The repository with the code is located here:
aws-serverless-hands-on-template.

The README.md file provides a tl;dr version of the deployment steps. You can simply fork the repo, make a few adjustments, and deploy. In the next section, we will explore each part in more detail.

Workstation Requirements

Before we begin the hands on portion, ensure that the following prerequisites are met:

You have AWS account that you can use
Your local station is properly configured and AWS CLI is working with your account AWS CLI Docs
You have a basic understanding of AWS CDK Getting started with CDK
Node.js and npm are installed on you workstation Install Node/NPM
Your AWS environment has been bootstrapped properly CLI-bootstrap

Once these requirements are met, you're ready to proceed!

OIDC Stack

Before we begin with deployment, we need to ensure that GitHub is connected to our AWS account. The first step is to modify deploy/cdk/lib/components/oidc.ts file. In this file there is an oidc class where we specify which GitHub repository can assume the role

export class oidc{
  constructor(scope: Construct, rolename: string, repo: string, provider: GithubActionsIdentityProvider) {
    const accessSSMRole = new GithubActionsRole(scope, rolename, {
        provider: provider,   
        owner: '<your_github_owner>',
        repo: repo,
        roleName: rolename
    });   accessSSMRole.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName('PowerUserAccess'));
  }
}

Adjusting the role

Replace with the owner of your GitHub repository.
Since this is test code, I have assigned the PowerUserAccess policy to simplify deployment.
⚠️ This is NOT best practice. If you plan to use this in a production environment, consider implementing a custom policy with the necessary permissions (least privilege approach).

Deploying the OIDC Stack
Once the role is adjusted, deploy the stack using the following commands:

cd deploy/cdk
npm i -D aws-cdk-github-oidc
npm run cdk deploy OidcStack -- --profile <your_aws_profile>

After a few seconds, the deployment should be complete, and runners triggered from our GitHub repository should be able to authenticate with AWS.

Defining the Role in the Main Stack
The role name we can be defined in the main stack located in deploy/cdk/lib/oidc-stack.ts

new components.oidc(this, "github-actions-role", "aws-serverless-hands-on-template", provider);

Make sure to update the role name and repository name accordingly. Additionally, this change must be reflected in the GitHub Actions Workflow, which we will cover in the GitHub Actions Deployment section.

Backend Stack

The Backend Stack is responsible for creating the Lambda function, API Gateway, and DynamoDB table. The code for this stack is located in deploy/cdk/lib/backend-stack.ts.
The implementation is straightforward, but one important point to highlight is CORS (Cross-Origin Resource Sharing). Without CORS headers, the API Gateway would block frontend requests from CloudFront. To resolve this, we explicitly define the necessary CORS headers in the API Gateway response.

Configuring CORS in API Gateway
To allow the frontend to access the backend, we need to modify the API Gateway responses:

    resource.addMethod('GET', lambdaIntegration, {
        methodResponses: [
            {
                statusCode: '200',
                responseParameters: {
                    'method.response.header.Access-Control-Allow-Origin': true,
                    'method.response.header.Access-Control-Allow-Methods': true,
                    'method.response.header.Access-Control-Allow-Headers': true,
                },
            },
        ],
    });

Additionally, we define CORS options on API resources, ensuring that data can be shared between the backend and frontend:

    resource.addCorsPreflight({
        allowOrigins: ['*'],
        allowMethods: ['GET', 'POST', 'OPTIONS'],
        allowHeaders: ['Content-Type', 'X-Amz-Date', 'Authorization', 'X-Api-Key', 'X-Amz-Security-Token'],
    });

Exposing API Gateway URL
This stack also outputs the API Gateway URL, which is used in the Frontend Stack to automate the deployment process. This prevents the need for manual updates.

new CfnOutput(this, 'API_URL', { value: api.url })

The API_URL is later updated dynamically in the frontend configuration via GitHub Actions, which we will cover in the CI/CD section.

Lambda Function
The Lambda function is located in the deploy/cdk/lambda/index.js file. The handler logic is straightforward:

GET request → Reads from DynamoDB. Returns 400 if no value is provided or 200 on success.
POST request → Writes to DynamoDB. Returns errors for a few predefined conditions.

Connecting to DynamoDB & CORS
At the beginning of the Lambda function, we initialize the DynamoDB client and define CORS headers to allow cross-origin access:

const dynamoClient = new DynamoDBClient();
const docClient = DynamoDBDocumentClient.from(dynamoClient);

const headers = {
    "Access-Control-Allow-Origin": "*", 
    "Access-Control-Allow-Methods": "OPTIONS,GET,POST",
    "Access-Control-Allow-Headers": "Content-Type",
};

This ensures that requests from the frontend can communicate with the backend without CORS restrictions.

Frontend Stack

Before diving into the details, I have to admit that I had no experience working on the frontend side. So, I teamed up with ChatGPT, which helped me generate a simple index.html, style.css, and script.js to make things work.

**Main Structure (index.html)
The core part of the frontend is the index.html file. The key section is:

<body>
    <div class="container">
        <h1>Welcome to the Serverless App</h1>
        <h2>Please leave the trace and add yourself as visitor. You can then check the data if anyone is from your city!</h2>
        <button id="fetchVisitors">Fetch Data from Backend</button>
        <button id="addVisitor">Add Data</button>
        <pre id="output"></pre>
    </div>
    <script src="script.js"></script>
</body>

Key Elements

The two buttons (fetchVisitors and addVisitor) allow users to interact with the backend.
The script.js file is referenced at the bottom—it handles the logic when buttons are clicked.

Handling API Calls (script.js)
The first line of script.js defines the API_URL, which is dynamically replaced during the GitHub Actions (GHA) deployment step:

const API_URL = 'PLACEHOLDERdata';

During deployment, GitHub Actions replaces PLACEHOLDERdata with the actual API Gateway URL from the Backend Stack, ensuring that the frontend communicates with the correct backend.

Event Listeners for Button Clicks
Inside script.js, we listen for the DOMContentLoaded event and define what happens when each button is clicked:

"Fetch Data from Backend" button → Sends a GET request to API Gateway.
"Add Data" button → Sends a POST request with user input to the backend. The logic is straightforward, so you can go through the code and let me know if you have any questions.

GitHub Actions Deployment

This is the most crucial part of our setup, as it automates the deployment of our stacks through a CI/CD pipeline. The workflow file is located in the ./github/workflows folder. Let’s go through it step by step.

Workflow Configuration

name: Deploy serverless app to AWS
on:
  workflow_dispatch:
  # push:
  #   branches:
  #     - main

permissions:
  id-token: write
  contents: read

Apart from defining the workflow name, we should remove the # comments from lines 4-6 in the forked repository.
I commented out those lines in the template repo to prevent automatic pipeline runs.
The workflow_dispatch event allows us to manually trigger the workflow (when working on the main branch).
The permissions section is crucial for configuring AWS credentials, it must be included for the workflow to function properly.

Job Definition

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      AWS_ACCOUNT: '<your_AWS_ACCOUNT>'

We define one job, named deploy.
The job runs on Ubuntu (ubuntu-latest), a default GitHub runner with pre-installed packages.
The AWS account number is stored in the AWS_ACCOUNT environment variable.

Deployment Steps

Checkout Code

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

The first step is checking out the repository code.
Instead of writing custom scripts, we use a pre-built action from GitHub Market Place.

Set Up Node.js

      - name: Set Up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

This step ensures Node.js v18 is installed

Install Dependencies & Run Tests

      - name: Install Dependencies & test
        run: |
          pushd /home/runner/work/aws-serverless-hands-on/aws-serverless-hands-on/deploy/cdk
          npm install -g aws-cdk
          npm install
          npm test

Installs AWS CDK, project dependencies, and executes unit tests before proceeding.

Configure AWS Credentials

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT }}:role/github-actions-role
          aws-region: eu-west-1

This step assumes the IAM role created in the OIDC Stack, allowing GitHub Actions to deploy resources in our AWS account.

Deploy Backend and Frontend
Deploy Backend Stack

      - name: Deploy Backend
        id: backend
        run: |
          pushd /home/runner/work/aws-serverless-hands-on/aws-serverless-hands-on/deploy/cdk
          cdk deploy BackendStack --require-approval never --outputs-file cdk.outputs.json
          API_URL=$(jq -r '.["BackendStack"]["APIURL"]' cdk.outputs.json)
          echo "API_URL=$API_URL" >> $GITHUB_OUTPUT

The BackendStack is deployed first.
The API Gateway URL is captured in cdk.outputs.json and stored as API_URL.
We assign an ID (backend) to this step, making it easier to reference its output later.

Deploy Frontend Stack

      - name: Deploy Frontend
        run: |
          echo ${{ steps.backend.outputs.API_URL }}
          pushd /home/runner/work/aws-serverless-hands-on/aws-serverless-hands-on/deploy/cdk
          sed -i 's|PLACEHOLDER|'${{ steps.backend.outputs.API_URL }}'|g' frontend/script.js
          cdk deploy FrontendStack --require-approval never

The frontend deployment retrieves the API_URL from the backend deployment step.
It replaces the PLACEHOLDER in frontend/script.js with the actual API Gateway URL.
Finally, the FrontendStack is deployed.

Checking Deployment Output*
It might take up to 8-10 minutes. Once completed, the pipeline should be green.
To find the **CloudFront URL, click on Deploy Frontend scroll down a little bit, and look for the output:

Outputs:
FrontendStack.DistributionId = d1gmj3c7gkt5q0.cloudfront.net

And maybe it would be also helpful to see how it looks in practice.

Costs and Considerations

We did it! If everything went well your serverless app should not be up and running.
If you encountered any issues or found some sections unclear, feel free to leave a comment!

Why This Exercise Matters
Personally I believe that hands-on projects like this are an excellent way to gain real-world experience with AWS infrastructure, cloud services and automation. While going through each stage carefully can be time-consuming, the knowledge and confidence you gain are absolutely worth it.

Costs Breakdown
The good news is that this hands-on project is extremely cost-effective.
On my personal AWS account, I did not pay a single dollar, even though my deployed stacks remained active for nearly a month with multiple tests. This is thanks to AWS's Free Tier, which provides generous limits across various services.
Here’s a quick breakdown of the AWS Free Tier benefits relevant to this project:
Lambda has 1 milion requests per month free,
API GW for first 12 months 1 milion requests are also free but even if not, I would say we could spend <1$ if actively used during labs.

S3 Upon sign-up, new AWS customers receive 5GB of Amazon S3 storage in the S3 Standard storage class for first 12 months (per month)
DynamoDB provides 25GB of storage, along with 25 provisioned Write and 25 provisioned Read Capacity Units (WCU, RCU) which is enough to handle 200M requests per month
CloudFront 1 TB of data transfer out to the internet per month
10,000,000 HTTP or HTTPS Requests per month

Sources - you can find here
Note: After the free-tier limits expire, costs will vary depending on usage. However, even moderate activity is unlikely to exceed a few dollars per month.

Final Thoughts
This project also demonstrates how cost efficient serverless architectures can be. With AWS pay-as-you-go pricing and Free Tier, you can experiment and learn without worrying about high costs.

Thanks a lot for reading!

If you have any feedback, questions, or issues just let me know.

AWS Serverless hands on part 1/2

Piotr Popiolek — Tue, 11 Feb 2025 07:47:08 +0000

Introduction

When I started my cloud journey six years ago, serverless architecture was the most difficult concept for me to understand . I transitioned into DevOps world from an OnPrem engineer role (primarily working with mostly PoverVM and VMware). So if someone told me that they were running their app on the serverless schema, I could not really get it.
This post aims to make the serverless topic easier to understand by providing both theoretical insights and a hands-on practical approach. The article is split into two parts to separate planning from implementation, making it easier to absorb.

Our Action Plan

Part One:
- Introduction
- Main Idea: What we want to achieve
- Architecture of our app
- Assumptions and declarations
Part Two:
- Detailed app description
- OIDC implementation
- Backend implementation
- Frontend implementation
- Deployment with GitHub Actions (GHA)
- Considerations
- Costs analysis

What Do We Want to Achieve?

In my experience, the best way to learn is by combining theoretical knowledge with practical experimentation. This post will focus on understanding the basics of serverless architecture and then implementing a fully automated serverless app on AWS.
And when we say serverless, we mean a cloud computing model where developers can build and run applications without having to manage the underlying server infrastructure.
Of course the servers are still involved, but they are abstracted away from the user by the cloud provider. This allows developers to focus on writing and deploying code while the cloud provider takes care of server management (like scaling, provisioning, maintenance etc).
We are going to use several AWS services to power our application and we will rely on automation tools to avoid making manual changes through AWS Console. I think the plan is ambitious and assumes that the readers have a basic understanding about of IT concepts and are eager to learn more.
Let's dive in!

Architecture and overview the services

Our application will include both a backend and a frontend. Deployment and resource creation will be fully automated. Following best DevOps practices, all changes will be tracked through code ensuring:

Orderly cloud resource managment
Rapid recovery capabilities
Full transparency of changes
Minimized human error

Let's now go through services we will use.

Backend Services

AWS API Gateway (fully managed service to create/publish/maintain/monitor and secure API at any scale)
AWS Lambda (serverless compute service that runs the code without provisioning or managing servers, max timeout = 15 mins)
AWS DynamoDB (fully managed NoSQL database service designed for HA, performance and scalability)

Frontend Services

AWS CloudFront (content delivery network [known as CDN] service that accelerates the delivery of static and dynamic web content to users globally)
AWS S3 bucket (scalable object storage service designed to store and retrieve any amount of data at anytime anywhere)

High-Level Architecture Overview

Main Assumptions

All services will be created using Infrastructure as Code (IaaC) via AWS CDK (Cloud Development Kit). AWS CDK is a software development framework that allows to define cloud infrastructure using code in many programming languages (like TypeScript, Python, Java).
Unlike declarative templates like YAML or JSON, CDK uses programming constructs as building blocks. The stacks defined in CDK correspond to CloudFormation stacks containing all created resources. If you are new to CDK, check out the official AWS CDK docs for more details.

Our codebase will reside on GitHub, and any changes will trigger deployments via GitHub Actions.

A Note on GitHub Actions (GHA)
GitHub Actions is an automation platform integrated into GitHub, allowing developers to automate workflows within repositories. Workflows can handle tasks like building, testing, deploying, and maintaining applications.

Workflows are triggered by events such as:

Pushes (new code is pushed to a branch)
Pull Requests (opened/merged or updated)
Manual triggers (or other GitHub events)

In our case, we’ll create a simple workflow to deploy CDK constructs, ensuring AWS resources remain up to date.

Using OIDC for Secure Communication
To securely connect AWS with GitHub, we’ll use OpenID Connect (OIDC), a secure authentication protocol. OIDC enables GitHub Actions to authenticate with AWS without requiring long-lived credentials, reducing the risk of credential exposure.

It works as follow:

GitHub Actions acts as OIDC IdP (Identity Provider), allowing AWS to verify workflow identities via signed token
On AWS, the IAM role is configured to trust GitHub OIDC provider, with conditions specifying which repositories and workflows can assume the role
GitHub Actions uses the OIDC token to assume the trusted IAM role, obtaining temporary credentials to access AWS

First part summary

In this first part, we’ve covered:

Key services that we’ll use in our project
A high-level overview of our goals and architecture
An introduction to the tools and technologies involved

I hope everything is clear so far! Please leave a comment if you have any concerns or need further clarification. When you are ready, move on to the next part