DEV Community: Faruq Abdulsalam

How to Invoke a Lambda Function via API Gateway Locally Using Terraform and LocalStack (PDF Generator – Part 3)

Faruq Abdulsalam — Mon, 17 Feb 2025 09:17:11 +0000

In my previous article, How to Build and Test a PDF Generator Lambda Using LocalStack on Your Local Machine (Part 2: Using Terraform), we set up the foundational infrastructure, including S3, ECR, a Lambda function, and an IAM role using Terraform.

In this part, we’ll take it further by integrating API Gateway to invoke the Lambda function locally using LocalStack—allowing you to simulate real-world AWS behavior entirely on your local machine. This is particularly useful when you need to trigger Lambda functions via HTTP, just as you would in a production environment.

I’ve kept this guide simple and practical, so all you need is some basic Terraform knowledge to follow along.

Let's get started!

Prerequisites

Before proceeding, ensure you have the following installed:

Docker
Python 3.9+
LocalStack account
LocalStack CLI
LocalStack Desktop
Terraform

1. locals.tf
In this step, we'll introduce two new local variables specifically for the API Gateway resources. These variables define the names for the API Gateway and its deployment stage:

locals {
  ...
  api_gateway_name       = "pdf-generator-api"
  api_gateway_stage_name = "prod"
  ...
}

2. main.tf
Add the following code blocks below to the main.tf file:

rest api

resource "aws_api_gateway_rest_api" "lambda_api" {
  name        = local.api_gateway_name
  description = "API Gateway for invoking the PDF Generator Lambda function"

  endpoint_configuration {
    types = ["REGIONAL"]
  }
}

This block above creates the API Gateway REST API. We assign its name using the local variable we defined earlier: local.api_gateway_name.

The endpoint_configuration is set to REGIONAL, which is suitable because; we wont be using CloudFront and the API is not private(it will be accessible within the region).

resource

resource "aws_api_gateway_resource" "pdf_generator_api_root" {
  rest_api_id = aws_api_gateway_rest_api.lambda_api.id
  parent_id   = aws_api_gateway_rest_api.lambda_api.root_resource_id
  path_part   = "generate-pdf"
}

This block creates a new API Gateway resource, linking it to the previously created REST API using rest_api_id. We also define the parent_id and set the path to /generate-pdf, which establishes the resource's URL path under the API Gateway.

method

resource "aws_api_gateway_method" "pdf_generator_api_method" {
  rest_api_id      = aws_api_gateway_rest_api.lambda_api.id
  resource_id      = aws_api_gateway_resource.pdf_generator_api_root.id
  http_method      = "POST"
  authorization    = "NONE"
  api_key_required = false

}

This block creates the method for the resource above. It links the method to the REST API as well as the resource, and specifies the HTTP method as POST. Since we don't need authorization or an API key in this case, we set them to "NONE" and false, respectively.

integration

resource "aws_api_gateway_integration" "pdf_generator_api_integration" {
  rest_api_id = aws_api_gateway_rest_api.lambda_api.id
  resource_id = aws_api_gateway_resource.pdf_generator_api_root.id
  http_method = aws_api_gateway_method.pdf_generator_api_method.http_method

  type                    = "AWS_PROXY"
  integration_http_method = "POST"
  uri                     = aws_lambda_function.pdf_generator.invoke_arn

  depends_on = [aws_lambda_function.pdf_generator]

}

This block creates the integration for the method above, linking it to the REST API, the resource, and the HTTP method. It specifies an AWS_PROXY integration type, which allows direct communication between API Gateway and the Lambda function. The integration HTTP method is set to POST, and the URI points to the Lambda function’s invoke ARN. The depends_on attribute ensures that the Lambda function is created before the integration is established.

deployment

resource "aws_api_gateway_deployment" "lambda_api_deployment" {
  rest_api_id = aws_api_gateway_rest_api.lambda_api.id
  stage_name  = local.api_gateway_stage_name

  lifecycle {
    create_before_destroy = true
  }

  triggers = {
    redeployment = sha1(jsonencode([
      aws_api_gateway_resource.pdf_generator_api_root.id,
      aws_api_gateway_method.pdf_generator_api_method.id,
      aws_api_gateway_integration.pdf_generator_api_integration.id
    ]))
  }

  depends_on = [
    aws_api_gateway_integration.pdf_generator_api_integration
  ]

}

This block creates a deployment for the API, linking it to the REST API and specifying the stage name, which was declared earlier as a local variable. The lifecycle block ensures that the deployment is created before any resources are destroyed, minimizing downtime. The triggers attribute uses a SHA1 hash of the resource, method, and integration IDs to trigger a redeployment when changes occur. The depends_on attribute ensures that the deployment happens only after the API integration is fully created.

permission

resource "aws_lambda_permission" "apigw_lambda_permission" {
  action        = "lambda:InvokeFunction"
  function_name = aws_lambda_function.pdf_generator.function_name
  principal     = "apigateway.amazonaws.com"
  source_arn    = "${aws_api_gateway_rest_api.lambda_api.execution_arn}/${local.api_gateway_stage_name}/*"

  lifecycle {
    replace_triggered_by = [aws_lambda_function.pdf_generator]
  }

  depends_on = [aws_lambda_function.pdf_generator, aws_api_gateway_deployment.lambda_api_deployment]
}

This block grants the necessary permission for the API Gateway endpoint to invoke the Lambda function. The action is set to "lambda:InvokeFunction", allowing the API Gateway to trigger the Lambda. The source_arn specifies the ARN of the API Gateway’s execution role and stage. The lifecycle block ensures that the permission is replaced if the Lambda function changes, and the depends_on attribute ensures the permission is created only after the Lambda function and API Gateway deployment are in place.

3. outputs.tf
Finally, create a new file named outputs.tf in the root of the infrastructure directory and add this content.

output "rest_api_url" {
  description = "The URL of the API Gateway REST API"
  value       = "https://${aws_api_gateway_rest_api.lambda_api.id}.execute-api.localhost.localstack.cloud:4566/${local.api_gateway_stage_name}"
}

This block creates an output for the URL of the API Gateway REST API. Normally, the URL follows the format: https://{rest_api_id}.execute-api.{region}.amazonaws.com/{stage_name}.

However, since we're working with LocalStack in our local environment, the URL format is slightly different. It omits the region and amazonaws.com parts, and instead uses localhost.localstack.cloud as the base domain. This allows us to interact with the API locally.

The rest_api_id is simply the ID of the REST API, and there’s no difference in how it's used here. The stage_name corresponds to the local variable defined earlier in the locals.tf file

At this point, we have completed the code needed to provision the API Gateway resources and retrieve the URL. The next step is to create the resources and test our new implementation.

Run tflocal plan to get an overview of all the AWS resources that will be created. Then, run tflocal apply to confirm and initiate the creation of the resources.

Afterward, you should see the output of your API Gateway URL in the terminal. As explained earlier, the URL will have a format similar to this: https://{your_rest_api_id}.execute-api.localhost.localstack.cloud:4566/prod

Invoke lambda function

To test the Lambda function, we won’t invoke it directly. Instead, we will use the URL mentioned above. You can use Postman to make a POST request to https://{your_rest_api_id}.execute-api.localhost.localstack.cloud:4566/prod/generate-pdf (API Gateway URL + the path to the resource we created generate-pdf ) with the following payload:

{"first_name": "John", "last_name": "Doe"}

This is the same payload we previously used with the event.json file.

Alternatively, you can use curl to make the request. Here's the curl command:

curl -X POST https://{your_rest_api_id}.execute-api.localhost.localstack.cloud:4566/prod/generate-pdf \
  -H "Content-Type: application/json" \
  -d '{"first_name": "John", "last_name": "Doe"}'

You should see the success message below:

{"message": "PDF generated and uploaded successfully!"}

You can confirm that the PDF was successfully generated and stored in the S3 bucket by navigating to the bucket via the LocalStack Desktop and downloading the PDF.

Congratulations! 🎉

You’ve successfully set up your API Gateway, linked it to your Lambda function, and tested it locally using Terraform and LocalStack—all without needing an AWS account. Thanks for reading!

How to Build and Test a PDF Generator Lambda Using LocalStack on Your Local Machine (Part 2: Using Terraform)

Faruq Abdulsalam — Wed, 29 Jan 2025 10:09:25 +0000

This article is a follow-up to my previous post, article How to Build and Test a PDF Generator Lambda Using LocalStack on Your Local Machine

In that article, I walked you through how to build and test a PDF generator Lambda function locally using mock AWS services—AWS Lambda, Elastic Container Registry (ECR), and S3 buckets—via LocalStack. We used the awslocal CLI to provision the required infrastructure.

In this follow-up, we'll take a different approach. Instead of using the CLI, we'll use Terraform, an Infrastructure as Code (IaC) tool, to provision our resources. This guide will be simple and straightforward, so basic Terraform experience is all you need to follow along.

If you haven’t read the previous article yet, I highly recommend checking it out first as it covers the PDF generation logic itself, which we won’t be repeating here.

Let's get started

Prerequisites

Before proceeding, ensure you have the following installed:

Docker
Python 3.9+
LocalStack account
LocalStack CLI
LocalStack Desktop
Terraform

1: Restart the LocalStack Container

To ensure a clean environment and avoid any conflicts with previously provisioned services, you need to restart your LocalStack container. This step is important because it allows us to reuse the resource names used in the last article.

You can terminate the currently running container by pressing CTRL + C command , or you can stop the container directly using the LocalStack Desktop application. Then restart the container by running this command DEBUG=1 localstack start.

2. Install the terraform-local package
In the root directory named localstack, please activate your virtual environment if it is not already active.

Then, install the terraform-local package, which is a wrapper script that allows you to use Terraform to deploy resources to your LocalStack environment. This tool simplifies using Terraform locally with LocalStack, providing a smooth integration between the two.

pip install terraform-local

3. Creating Infrastructure

Next, create a new folder called infrastructure. This folder will house the following files:

locals.tf
versions.tf
main.tf
scripts/build_and_push_lambda_image.sh

Let's take a closer look at each of these files and their roles in setting up the infrastructure.

1. locals.tf

locals {
  aws_region      = "eu-west-1"
  pdf_bucket_name = "my-pdf-bucket"
  pdf_ecr_name    = "pdf-generator-image"
  pdf_generator_lambda = {
    function_name = "pdf-generator-lambda"
  }
}

In the locals.tf file, we define some basic variables that will be used throughout our Terraform configuration. Here, we specify the AWS region, the name of the S3 bucket, the name of the ECR repository, and the Lambda function name.

2. versions.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.59.0"
    }

    random = {
      source  = "hashicorp/random"
      version = "~> 3.6.2"
    }
  }
}

provider "aws" {
  region = local.aws_region

}

In the versions.tf file, we specify the required providers for our Terraform configuration. We define the AWS provider (hashicorp/aws) to interact with AWS services, and the random provider (hashicorp/random) to generate random values like unique IDs. We also configure the AWS provider to use the region defined in the locals.tf file (local.aws_region). This file ensures that Terraform uses the correct providers and versions when provisioning infrastructure.

3. main.tf

S3 Bucket

# Generate random string for the bucket name
resource "random_id" "pdf_bucket_suffix" {
  byte_length = 6
}

# S3 bucket for storing the generated PDF files
resource "aws_s3_bucket" "pdf_bucket" {
  bucket        = "${local.pdf_bucket_name}-${random_id.pdf_bucket_suffix.hex}"
  force_destroy = true

  lifecycle {
    prevent_destroy = false
  }

  tags = {
    Name = "${local.pdf_bucket_name}"
  }
}

We first create a random_id resource to generate a random string, which will be appended to the name of the S3 bucket, ensuring it is unique. The byte_length = 6 specifies the length of the random string. Then the aws_s3_bucket resource is created using the bucket name defined by the local variable (local.pdf_bucket_name) combined with the random suffix. We also configure the bucket to allow forced destruction (force_destroy = true) which means it can be deleted even if it contains objects. Finally, the lifecycle block includes prevent_destroy = false setting, which ensures that Terraform won’t block the destruction of the bucket if needed.

Elastic Container Registry

# ECR repository for storing the Docker images
resource "aws_ecr_repository" "pdf_generator_ecr" {
  name = local.pdf_ecr_name
}

The aws_ecr_repository resource is used to create an ECR repository where the Docker image for the Lambda function will be stored. The repository name is defined using the local variable local.pdf_ecr_name.

Build and Push Image to ECR

# Run your existing image push script using null_resource
resource "null_resource" "run_build_and_push_image_script" {
  provisioner "local-exec" {
    command = "bash ${path.module}/scripts/build_and_push_lambda_image.sh"
    environment = {
      ECR_REPO_URI = aws_ecr_repository.pdf_generator_ecr.repository_url
    }
  }

  depends_on = [
    aws_ecr_repository.pdf_generator_ecr # Ensure the repository exists before running the script
  ]
}

Since we cannot create an empty lambda function, we would have to ensure we have an existing image before the lambda function itself is created. So we can do that using the null_resource block to call our script scripts/build_and_push_lambda_image.sh that'll build the Docker image for our pdf generator function and deploys it to the ECR repository defined in the configuration. We'll add content to the script after completing the main.tf file.

In this null_resource block, we pass the ECR_REPO_URI environment variable to the build_and_push_lambda_image.sh script, which allows it to dynamically use the correct Amazon ECR repository URL for pushing the built Docker image. The depends_on array ensures that the script runs only after the ECR repository (aws_ecr_repository.pdf_generator_ecr) is created, preventing any issues from attempting to push an image to a non-existent repository.

Disclaimer: The approach used in this tutorial is for educational purposes only. While Terraform is a powerful tool for provisioning infrastructure, using it to build and push Docker images is not advisable for production environments. In production, it's best to use a dedicated CI/CD pipeline to manage your application artifacts.

IAM role

# IAM Role for Lambda Execution
resource "aws_iam_role" "pdf_generator_lambda_role" {
  name = "ExecRole-${local.pdf_generator_lambda.function_name}"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Sid    = ""
        Principal = {
          Service = "lambda.amazonaws.com"
        }
      },
    ]
  })
}

The aws_iam_role.pdf_generator_lambda_role IAM role allows the Lambda function to assume the necessary permissions for execution. It grants the Lambda service permission to interact with AWS resources securely by defining the assume_role_policy with the appropriate permissions.

Lambda function

# Lambda Function for PDF Generation
resource "aws_lambda_function" "pdf_generator" {
  function_name = local.pdf_generator_lambda.function_name
  role          = aws_iam_role.pdf_generator_lambda_role.arn
  package_type  = "Image"
  image_uri     = aws_ecr_repository.pdf_generator_ecr.repository_url
  timeout       = 60
  memory_size   = 128
  architectures = ["arm64"]

  environment {
    variables = {
      S3_BUCKET_NAME = aws_s3_bucket.pdf_bucket.bucket
    }
  }

  depends_on = [
    aws_ecr_repository.pdf_generator_ecr,         # Ensure the ECR repo exists before pushing the image
    null_resource.run_build_and_push_image_script # Ensure the script runs before Lambda is created
  ]
}

Here we define the pdf_generator Lambda function, specifying the function name, IAM role, and container image from the ECR repository. The Lambda is allocated 128MB of memory and a 60-second timeout, using arm64 architecture. We set an environment variable for the S3 bucket name. The depends_on block ensures that the Lambda is created only after the ECR repository exists and the Docker image is built and pushed.

Note: If your local development machine or the environment where you’re building the Lambda function uses a different architecture, such as x86_64 (common for many Linux or Windows machines), you can adjust the architectures array value from arm64 to x86_64.

4. scripts/build_and_push_lambda_image.sh

#!/bin/bash

# Get the ECR URI from the environment variable
ECR_REPO_URI=$ECR_REPO_URI

# Now you can use the $ECR_REPO_URI in the script
echo "ECR URI: $ECR_REPO_URI"

# get the current directory
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

# Navigate to the lambda function directory
echo "Navigating to lambda function directory..."
cd $SCRIPT_DIR/../../pdf-generator-lambda || exit 1

echo "Current directory: $(pwd)"

# Build the docker image
echo "Building the docker image..."
docker build --no-cache -t lambda-container-image .

# Tag the image with the ECR repository URI
echo "Tagging the docker image with the ECR repository URI..."
docker tag lambda-container-image $ECR_REPO_URI

# Push the image to the ECR repository
echo "Pushing the docker image to the ECR repository..."
docker push $ECR_REPO_URI

echo "Script execution completed."

This script builds the PDF generator Lambda function as a Docker image, tags it, and pushes it to the specified ECR repository. The ECR_REPO_URI is passed as an environment variable from the null_resource block in the main.tf file.

This completes the necessary Terraform configuration. Before we proceed to create the infrastructure using the installed tflocal package, let's make a small change to the upload_file.py script that handles uploading the generated PDF file to the S3 bucket. Previously, we hardcoded the bucket-name; now, we'll retrieve it from the environment as an environment variable instead.

upload_file.py

import os

.....
S3_BUCKET_NAME = os.environ.get("S3_BUCKET_NAME")

.....

Import the os module and modify the line above so that the script uses the S3_BUCKET_NAME environment variable instead of relying on a hardcoded value.

Now we are ready to create our infrastructure. From inside the infrastructure directory, run

tflocal init

This will initialize Terraform and generate some files once it runs successfully. Next, run

tflocal plan

This will return an overview of all the AWS resources that will be provisioned and set up in the active LocalStack container. You should see a line similar to: Plan: 6 to add, 0 to change, 0 to destroy.

Finally, run

tflocal apply

to create the resources. This will display an overview similar to what you saw earlier when running tflocal plan, and it will ask you to confirm whether you want to proceed. Simply type yes, and all your resources will be created in LocalStack. For a sanity check, you can use either the AWS CLI or the LocalStack Desktop to verify that the following resources have been created: S3 bucket, ECR repo, and Lambda function.

Now, let's invoke our Lambda function. Navigate back to the pdf-generator-lambda directory and run the following command:

awslocal lambda invoke --function-name pdf-generator-lambda --payload file://event.json /tmp/lambda.out

You should receive a success message like this:

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

You can confirm that the PDF was successfully generated and stored in the S3 bucket by navigating to the bucket via the LocalStack Desktop and downloading the PDF.

Congratulations! 🎉
You’ve successfully set up and tested your infrastructure using Terraform and LocalStack. Thank you for reading!

How to Build and Test a PDF Generator Lambda Using LocalStack on Your Local Machine

Faruq Abdulsalam — Thu, 16 Jan 2025 09:46:06 +0000

Have you ever struggled with adding a PDF generation feature to your application? I’ve certainly faced that pain more than a few times. Whether it’s generating receipts, weekly or monthly reports, or just about anything else, PDF generation is a feature that seems to pop up in almost every project I’ve worked on. Technology is fascinating, and users are always pushing for features that make their lives easier—and let’s face it, users are always right 😉.

In this part of the series, I’ll walk you through how to easily create a Lambda function that handles PDF generation. We’ll build the function as a Docker image, push it to the local Elastic Container Registry (ECR) service within LocalStack, and then test it locally. To validate the generated PDF, we’ll also integrate the local S3 service in LocalStack. This setup enables you to develop, test, and debug your Lambda function entirely on your local machine before deploying it to the AWS cloud.

If you haven’t already read my previous article on working with AWS S3 locally using LocalStack, I highly recommend giving it a read. It covers the setup of both the LocalStack environment and your development environment, along with easy steps for working with AWS S3 in LocalStack. In this article, we'll be building on that foundation as we create a Lambda function for PDF generation and integrate it with LocalStack’s S3 service. You can find that previous article here.

Buckle up and enjoy the ride!

Prerequisites

Docker
Python 3.9+
LocalStack account
LocalStack CLI
LocalStack Desktop

FILES and CODE

Let's Start Coding! In this section, we will create a few essential files that will allow us to build and test our Lambda function for generating PDFs and uploading them to S3 using LocalStack.

We'll create a new directory called pdf-generator-lambda inside the localstack directory, where you previously set up your virtual environment. This new directory will contain the following files:

requirements.txt
Dockerfile
logger.py
pdf_generator.py
lambda_function.py
event.json
templates/test.html
upload_file.py

Let's walk through each of these files and their role in the project.

1. requirements.txt
This file lists the Python dependencies required for our Lambda function. These dependencies include:

Jinja2: A templating engine that allows you to create dynamic templates.
pdfkit: A Python wrapper for the wkhtmltopdf tool that converts HTML to PDFs.
boto3: The AWS SDK for Python, which is used to interact with AWS services such as S3.
botocore: A low-level, foundational library for interacting with AWS APIs, required by boto3.

Here’s the content for requirements.txt:

Jinja2==3.1.4
pdfkit==1.0.0
boto3==1.26.146
botocore==1.29.146

2. Dockerfile
The Dockerfile defines how the Lambda function will be packaged as a Docker container. It sets up the environment, installs dependencies, and copies the necessary files for your Lambda function. Here’s a breakdown of the Dockerfile:

Base Image: We’re using the official public.ecr.aws/lambda/python:3.10 base image for Lambda functions with Python 3.10. This image is pre-configured to run AWS Lambda functions.
Installing Dependencies: We install wkhtmltopdf with the correct binaries for either x86_64 or aarch64 architecture to ensure compatibility and other necessary tools that the Lambda function will need to generate PDFs.
Copying Code: We copy the Python files from the local environment into the Docker container.
Lambda Handler: The entry point of the Lambda function is defined as lambda_function.lambda_handler.

Here’s the content for the Dockerfile:

FROM public.ecr.aws/lambda/python:3.10

# Install necessary tools and clean up
RUN yum -y install gcc gcc-c++ unzip which \
    && yum clean all \
    && rm -rf /var/cache/yum

# Set the Lambda task root explicitly
ENV LAMBDA_TASK_ROOT=/var/task

# Copy and install Python dependencies
COPY ./requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip3 install --upgrade pip \
    && pip3 install --no-cache-dir -r requirements.txt

# Install wkhtmltopdf with architecture-specific binaries
RUN ARCH=$(uname -m) && \
    if [ "$ARCH" = "x86_64" ]; then \
        curl -L -o wkhtmltopdf.rpm "https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox-0.12.6-1.amazonlinux2.x86_64.rpm"; \
    elif [ "$ARCH" = "aarch64" ]; then \
        curl -L -o wkhtmltopdf.rpm "https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox-0.12.6-1.amazonlinux2.aarch64.rpm"; \
    fi && yum -y install wkhtmltopdf.rpm && rm -f wkhtmltopdf.rpm

# Optionally move wkhtmltopdf to /opt/bin and set permissions
RUN mkdir -p /opt/bin && mv /usr/local/bin/wkhtmltopdf /opt/bin/wkhtmltopdf && chmod +x /opt/bin/wkhtmltopdf

# Add app files
COPY . ${LAMBDA_TASK_ROOT}

# Set the command for Lambda runtime
CMD ["lambda_function.lambda_handler"]

3. logger.py
Here, we initialize the logger module, making it reusable across all scripts in the directory. The get_logger function sets up basic logging with a log level of INFO, and specifies a log format that includes the timestamp, logger name, log level, and the message. This logger is then returned and can be used in other scripts to maintain consistent logging throughout the project..

import logging

def get_logger():
    logging.basicConfig(
        level=logging.INFO,  # Set the minimum log level (DEBUG, INFO, WARNING, etc.)
        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",  # Log format
    )

    logger = logging.getLogger(__name__)
    return logger

4. pdf_generator.py
This script will handle the generation of PDFs using the pdfkit library, which works in conjunction with the wkhtmltopdf binary to render HTML templates into PDFs.

import pdfkit
import os
import jinja2
from logger import get_logger

TEMPLATES_DIR = os.path.join(os.path.dirname(__file__), "templates")
PATH_WKHTMLTOPDF = os.getenv("PATH_WKHTMLTOPDF", "/opt/bin/wkhtmltopdf")
KITOPTIONS = {
    "enable-local-file-access": None,
    "disable-smart-shrinking": "",
    "page-width": "157mm",
    "page-height": "222.77mm",
    "dpi": 400,
    "encoding": "UTF-8",
    "margin-top": "0cm",
    "margin-right": "0cm",
    "margin-bottom": "0cm",
    "margin-left": "0cm",
    "custom-header": [("Accept-Encoding", "gzip")],
    "no-outline": None,
}
TEMPLATE = os.path.join(TEMPLATES_DIR, "test.html")

logger = get_logger()


def handle_pdf_generation(body):
    """
    Handle PDF generation

    :param body: dict

    :return: binary_pdf
    """

    try:
        logger.info("Starting PDF generation")

        # Ensure templates directory exists
        if not os.path.exists(TEMPLATES_DIR):
            raise Exception(f"Templates directory not found at {TEMPLATES_DIR}")

        # Ensure template file exists
        if not os.path.exists(TEMPLATE):
            raise Exception(f"Template file {TEMPLATE} not found")

        # Load and render template
        template = jinja2.Template(open(TEMPLATE).read())
        rendered_template = template.render(data=body)

        # Configure pdfkit
        configuration = pdfkit.configuration(wkhtmltopdf=PATH_WKHTMLTOPDF)

        logger.info("Generating PDF")
        pdf_file = pdfkit.from_string(
            rendered_template,
            output_path=False,
            options=KITOPTIONS,
            configuration=configuration,
        )

        logger.info("PDF generated successfully")
        return pdf_file
    except OSError as e:
        logger.error(f"Error with wkhtmltopdf binary: {e}")
        raise Exception(f"Error with wkhtmltopdf binary: {e}")
    except Exception as e:
        logger.error(f"Error generating PDF: {e}")
        raise Exception(f"Error generating PDF: {e}")

5. lambda_function.py
This file will contain the logic for generating PDFs and uploading them to S3. We will use the handle_pdf_generation function to generate a PDF and upload_pdf to upload it to a local S3 bucket (using LocalStack).

import json
import random
from pdf_generator import handle_pdf_generation
from upload_file import upload_pdf
from logger import get_logger


logger = get_logger()


def lambda_handler(event, context):
    logger.info(f"Received event: {event}")
    try:
        body = event.get("body")
        if not body:
            raise Exception("No body found in the request")
        logger.info(f"Received body: {body}")

        # If body is a string, load it as JSON
        if isinstance(body, str):
            body = json.loads(body)

        logger.info("Generating PDF")
        pdf_result_data = handle_pdf_generation(body)

        file_name = "test_" + str(random.randint(1, 1000)) + ".pdf"

        logger.info(f"Uploading PDF to S3 with file name: {file_name}")
        upload_pdf(pdf_result_data, file_name)
        logger.info(f"PDF uploaded successfully to S3 as {file_name}!")

        return {
            "statusCode": 200,
            "body": json.dumps({"message": "PDF generated and uploaded successfully!"}),
        }

    except Exception as e:
        logger.error("Error: %s", e, exc_info=True)
        return {
            "statusCode": 500,
            "body": json.dumps({"error": f"Internal server error: {e}"}),
        }

6. event.json
This file contains a sample event that will be used to test our Lambda function.

{
  "body" : {"first_name": "John", "last_name": "Doe"}
}

7. templates/test.html
Create a test.html file inside the templates directory within the pdf-generator-lambda directory. This file will define a simple HTML structure that displays the first_name and last_name values passed to the Lambda function. The HTML will later be rendered and converted to a PDF.

Here’s the code to include in test.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Test Page</title>
    <link
      href="https://fonts.googleapis.com/css2?family=Poppins:wght@100;200;300;400;500;600;700&display=swap"
      rel="stylesheet"
    />
    <link
      href="https://api.fontshare.com/css?f[]=clash-display@400,700&display=swap"
      rel="stylesheet"
    />
    <link
      href="https://fonts.googleapis.com/css2?family=Roboto:wght@100;300;400;500;700&display=swap"
      rel="stylesheet"
    />
    <style>
      body {
        width: 595px;
        margin: 0 auto;
        font-family: "Poppins", sans-serif;
        font-size: 14px;
        line-height: 1.6;
        color: #333;
      }

      main {
        width: 100%;
        height: 100%;
      }

      a {
        color: #26639b;
        text-decoration: none;
      }

      h1 {
        font-size: 28px;
        font-weight: 600;
        color: #166082;
        margin-bottom: 20px;
        text-align: center;
      }

      .page-content {
        width: 100%;
        height: 100%;
      }

      .label {
        font-weight: 600;
        color: #166082;
        font-size: 14px;
      }

      .value {
        font-size: 14px;
        white-space: pre-line;
      }

      .detail {
        margin-bottom: 15px;
        padding-left: 55px;
        padding-right: 55px;
        padding-top: 5px;
      }

      .footer {
        margin-top: 20px;
        text-align: center;
        font-size: 12px;
        color: #888;
      }
    </style>
  </head>
  <body>
    <main>
      <div class="page-content">
        <h1>PDF GENERATOR</h1>
        <div class="detail">
          <span class="label">First Name:</span>
          <span class="value">- {{data.first_name}}</span>
        </div>
        <div class="detail">
          <span class="label">Last Name:</span>
          <span class="value">- {{data.last_name}}</span>
        </div>
      </div>
    </main>
    <div class="footer">
      <p>Generated by PDF Generator</p>
    </div>
  </body>
</html>

8. upload_file.py
This script handles uploading a generated PDF to an S3 bucket. It sets up a boto3 S3 client with mock AWS credentials and a LocalStack endpoint, specifically using the http://host.docker.internal:4566 URL to ensure communication between the Docker container and LocalStack. The upload_pdf function takes the PDF in byte format, wraps it in a BytesIO object, and calls the upload_to_s3 function, which handles the file upload.

The script now checks if the S3 bucket (my-pdf-bucket) exists before attempting the upload. If the bucket does not exist, an error message is logged, and an exception is raised. This ensures that the upload only occurs if the bucket is present. The check_bucket_exists function checks for the bucket's existence by calling the head_bucket operation. If the bucket is not found, the error is caught, and the appropriate message is logged.

If the S3_BUCKET_NAME environment variable is not set or is invalid, the script will log an error and raise an exception before attempting to upload the file, ensuring that the upload operation doesn't proceed without a valid bucket name.

import boto3
from logger import get_logger
from io import BytesIO
from botocore.exceptions import ClientError

logger = get_logger()

AWS_ACCESS_KEY_ID = "test"
AWS_SECRET_ACCESS_KEY = "test"
S3_BUCKET_NAME = "my-pdf-bucket"
BUCKET_REGION = "eu-west-1"
LOCALSTACK_HOST = "http://host.docker.internal:4566"  # Default LocalStack endpoint


def upload_to_s3(file_bytes, filename, mimetype, object_name=None):
    """
    Uploads a file to an S3 bucket

    :param file_bytes: Bytes object of the file to be uploaded
    :param filename: Name of the file
    :param mimetype: MIME type of the file
    :param object_name: Name of the object in the bucket

    :return: True if the file was uploaded, else False
    """

    if object_name is None:
        object_name = filename

    try:
        s3_client = create_S3_client()

        if not check_bucket_exists(s3_client, S3_BUCKET_NAME):
            logger.error(f"Bucket {S3_BUCKET_NAME} does not exist.")
            raise Exception(f"Bucket {S3_BUCKET_NAME} does not exist.")

        # Wrap the bytes object in a BytesIO object
        file_obj = BytesIO(file_bytes)

        # Upload the file object to S3 bucket
        s3_client.upload_fileobj(
            file_obj, S3_BUCKET_NAME, object_name, ExtraArgs={"ContentType": mimetype}
        )

        logger.info(f"{object_name} uploaded to {S3_BUCKET_NAME} bucket")
    except ClientError as e:
        logger.error(e)
        raise Exception(f"Error uploading file: {e}")
    except Exception as e:
        logger.error(e)
        raise Exception(f"Error uploading file: {e}")


def create_S3_client():
    """Create an S3 client."""

    s3_client = boto3.client(
        "s3",
        aws_access_key_id=AWS_ACCESS_KEY_ID,
        aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
        region_name=BUCKET_REGION,
        endpoint_url=LOCALSTACK_HOST,  # Point to LocalStack endpoint
    )

    return s3_client

def check_bucket_exists(s3_client, bucket_name):
    """Check if the S3 bucket exists."""
    try:
        s3_client.head_bucket(Bucket=bucket_name)
        return True  # Bucket exists
    except ClientError as e:
        # If the error is a 404, the bucket doesn't exist
        if e.response["Error"]["Code"] == "404":
            return False
        else:
            # Other errors, log and re-raise
            logger.error(f"Error checking if bucket exists: {e}")
            raise

def upload_pdf(file_bytes, filename):
    # Check if the S3 bucket name is valid
    if not S3_BUCKET_NAME:
        logger.error("S3_BUCKET_NAME is not set properly. The file cannot be uploaded.")
        raise Exception(
            "Invalid S3_BUCKET_NAME environment variable. File upload failed."
        )
    try:
        upload_to_s3(file_bytes, filename, "application/pdf")
        logger.info("File uploaded successfully!")
    except Exception as e:
        logger.error(f"Error: {e}")
        raise Exception(f"Error uploading file: {e}")

Now that we've covered all the files and code required, let's move on to setting up the services.

SERVICES SETUP AND TESTING

Before proceeding, ensure that your LocalStack container is up and running. If it isn’t already running, export your LOCALSTACK_AUTH_TOKEN and start a new container using the following command:

DEBUG=1 localstack start

S3 Bucket
First, let's create the S3 bucket where we'll store the generated PDFs. Run the following command to create a bucket named my-pdf-bucket:

awslocal s3 mb s3://my-pdf-bucket

Then verify the bucket creation via the CLI using awslocal s3 ls or by checking your LocalStack Desktop application.

Elastic Container Registry (ECR)
Now, let's create a repository in the Elastic Container Registry (ECR) to store the Docker image for the function. Run the command below to create a new repository:

awslocal ecr create-repository --repository-name pdf-generator-image

You should see a response similar to:

{
    "repository": {
        "repositoryArn": "arn:aws:ecr:eu-west-1:000000000000:repository/pdf-generator-image",
        "registryId": "000000000000",
        "repositoryName": "pdf-generator-imager",
        "repositoryUri": "000000000000.dkr.ecr.eu-west-1.localhost.localstack.cloud:4566/pdf-generator-image",
        "createdAt": 1736994302.0,
        "imageTagMutability": "MUTABLE",
        "imageScanningConfiguration": {
            "scanOnPush": false
        },
        "encryptionConfiguration": {
            "encryptionType": "AES256"
        }
    }
}

Please note down your repositoryUri as we'll need it in subsequent steps. If you clear your terminal after creating the repository, you can also easily retrieve these details later by running this command:

awslocal ecr describe-repositories

Docker Image
Now let’s time to build our Docker image, tag it with the repositoryUri from earlier, and push it to the Elastic Container Registry (ECR).

First, run the following command to build the Docker image:

docker build --no-cache -t lambda-container-image .

Once the build is complete, tag the image with your repository URI:

docker tag lambda-container-image 000000000000.dkr.ecr.eu-west-1.localhost.localstack.cloud:4566/pdf-generator-image

Note: Replace the repositoryUri in the command above with your own URI if it's different from the one provided in this example.

Finally, push the tagged image to ECR:

docker push 000000000000.dkr.ecr.eu-west-1.localhost.localstack.cloud:4566/pdf-generator-image

Note: Be sure to use the correct repositoryUri when tagging and pushing the image. Using the wrong repositoryUri or tagId will result in errors.

Lambda Function
Next, let's create the Lambda function using the image we uploaded to the Elastic Container Registry.

Run the following command to create the Lambda function:

awslocal lambda create-function \
--function-name pdf-generator-lambda \
--package-type Image \
--code ImageUri="000000000000.dkr.ecr.eu-west-1.localhost.localstack.cloud:4566/pdf-generator-image" \
--role arn:aws:iam::000000000000:role/lambda-role \
--handler lambda_function.lambda_handler \
--timeout 60 \
--architectures arm64

In this command:

We set the Lambda function name to pdf-generator-lambda.
The ImageUri refers to the repositoryUri of the image we uploaded earlier to ECR.
The handler specifies the entry point of the Lambda function. In this case, it's the lambda_handler function in the lambda_function.py file, which runs our entire process.
We set the timeout to 60 seconds to allow sufficient time for both PDF generation and the upload process. You can adjust this based on your system and the expected size of the PDF. Larger PDFs will take more time to generate and upload.
The architectures parameter is set to arm64 to match the architecture of my local processor. If you're using a machine with an x86_64 architecture, you should update this accordingly.

For a quick sanity check, run the following command to confirm that your Lambda function has been created:

awslocal lambda list-functions

This will list all Lambda functions deployed in your LocalStack environment. If successful, you should see your pdf-generator-lambda function in the output.

Finally, let's invoke our Lambda function to validate everything we've done. Run the following command:

awslocal lambda invoke --function-name pdf-generator-lambda --payload file://event.json /tmp/lambda.out

In this command:

--function-name specifies the name of the Lambda function to invoke, which is pdf-generator-lambda in this case.
--payload passes an input event to the function, simulating a real-world invocation. Here, the payload is sourced from the event.json file.
/tmp/lambda.out is the output file path where the logs generated by the Lambda function during execution will be stored.

After running the command, you should see the following response in your terminal, indicating that the Lambda function executed successfully:

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

To confirm that the function executed successfully, I'll be using the LocalStack Desktop application, as it simplifies downloading the generated PDF file from the S3 bucket. Navigate to the S3 resource in the resource list within your active container in the LocalStack Desktop interface. You should see your PDF file listed there. Click on it, and you’ll be prompted to download the file. Download the file and verify that it contains the expected content similar to the screenshot below.

If you can see the generated PDF, that means we have successfully created a Lambda function locally, built it as a Docker image, created an Elastic Container Registry, uploaded the image to it, set up an S3 bucket, invoked our Lambda function, and successfully generated a PDF that was stored in the S3 bucket. And the best part? We accomplished all of this without needing an actual AWS account. Pretty impressive, right?

Now, if you need to make changes to your Lambda function, you’ll have to repeat the process: rebuild the image, retag it, push it to the ECR, and then update the Lambda function with the new image. To update your Lambda function, you can use the following command:

awslocal lambda update-function-code \
--function-name pdf-generator-lambda \
--image-uri "000000000000.dkr.ecr.eu-west-1.localhost.localstack.cloud:4566/pdf-generator-image"

Congratulations! 🎉
You’ve reached the end of this article—thank you for reading! 😊 I hope to extend this series with more articles, so stay tuned.

If you have any questions, feel free to leave a comment or send me a message on LinkedIn. I’ll make sure to respond as quickly as I can. Ciao 👋

How to Simulate AWS S3 on Your Local Machine with LocalStack

Faruq Abdulsalam — Wed, 08 Jan 2025 09:43:29 +0000

In this article, I’ll walk you through the process of simulating an AWS S3 bucket in your local environment — no AWS account required. By the end, you’ll know how to create S3 buckets locally, upload files to them, and download the uploaded files with ease.

Prerequisites

LocalStack Setup

First, set up your LocalStack environment. If you’ve already done this, feel free to skip this section

LocalStack CLI
The first step is to install the LocalStack CLI(Command Line Interface). This link contains an easy guide on how to install the CLI depending on the OS of your machine.

LocalStack account
After successfully installing the CLI, create a LocalStack account here. This will give you access to your own dashboard, where you can manage your account, retrieve your auth token, manage subscriptions, monitor stack insights, and explore other features.

Note: You don't have to actually pay for any subscription if you are not using LocalStack for commercial purposes. LocalStack offers a Hobby Subscription for enthusiasts like myself. If you're not building for commercial purposes, you can select this option through the Subscriptions page in your dashboard. This will give you access to a wide range of open source as well as pro services and features.

LocalStack Desktop
Next I highly recommend you install the LocalStack Desktop application. This will be give you a visual display of your created services, logs, uploaded files e.t.c. This will be really helpful for conducting sanity checks.

LocalStack Authentication Token
You can find your authentication token on the Auth Tokens page of your dashboard. Make sure to set this variable before starting LocalStack:

export LOCALSTACK_AUTH_TOKEN="your-auth-token"

Configure your environment
Next, set the environment variables in your shell:

export AWS_ACCESS_KEY_ID="test"
export AWS_SECRET_ACCESS_KEY="test"
export AWS_DEFAULT_REGION="eu-west-1"

If your region is different (e.g., eu-central-1, us-east-1, etc.), be sure to update the AWS_DEFAULT_REGION to match.

Note: The variables set using this approach will only persist for the duration of the current shell session and will be cleared when the session ends. If you want to avoid repeating this process every time, you can configure a custom profile to use with LocalStack.

With everything in place, you're good to go! For a quick sanity check, make sure Docker is running on your machine (either using the CLI or Docker Desktop), and then run the following command in your shell to ensure everything is configured correctly:

DEBUG=1 localstack start

The DEBUG=1 command enables debug-level logging for LocalStack, allowing you to easily monitor and troubleshoot what's happening behind the scenes. While you'll see a lot of verbose information during startup, don't worry about it. Simply scroll to the bottom of the logs and look for this:

Ready.

If you see this message, it means LocalStack has started successfully. Now, open the LocalStack Desktop application, and you should see the new container in the list.

Local Environment Setup

Follow the following steps to properly set up your local environment.
1. Create a new directory:

mkdir localstack

2. Move into the new directory:

cd localstack

3. Create a virtual environment:
It’s recommended to create a virtual environment to avoid installing dependencies globally, which might conflict with dependencies for other projects on your machine.

For mac/unix users: 
python3 -m venv env
For windows users: 
py -m venv env

After creating the environment, activate it by running :

For mac/unix users: 
source env/bin/activate
For windows users: 
.\env\Scripts\activate

4. Install Boto3 for S3:

pip install boto3

This will install the boto3 library, which is the AWS SDK for Python. You will use it to interact with S3, and other AWS services, locally simulated by LocalStack.

5. Install the LocalStack AWS CLI(awslocal):

pip install 'awscli-local[ver1]'

This will install AWS CLI v1 in your new environment. Using a virtual environment ensures there’s no clash with an existing AWS CLI v2 installation (if you already have it installed, which is likely). The LocalStack documentation mentions certain limitations with AWS CLI v2, so sticking with v1 is recommended for this setup.

6.Verify the installation:
You can verify that the installation was succesful by running.

aws --version
# OR
awslocal --version

You should see something similar to this

aws-cli/1.36.34 Python/3.9.6 Darwin/24.1.0 botocore/1.35.93

If your output is similar, you're on the right track—let’s move on!

Create an S3 bucket in the LocalStack container

Even though we’re using LocalStack, remember that it’s designed to completely mock AWS services. This means we’ll still use AWS CLI commands to interact with our services.

The key difference is that instead of using the aws command, we’ll use the awslocal command. The reason for this is that awslocal is a thin wrapper around aws—it automatically appends the endpoint URL (your LocalStack URL) to every command you run.

If you decide to use the aws prefix instead, you’ll need to either configure the endpoint URL in your AWS profile or append it manually to every command. This approach is tedious and unnecessary, so I strongly recommend sticking with awslocal.

Create Bucket
Run the command below to create an S3 bucket with the name my-new-bucket

awslocal s3 mb s3://my-new-bucket

You should see the following response:

make_bucket: my-new-bucket

Verify the Bucket Creation via the CLI
To ensure the bucket has been created, list all available buckets using this command:

awslocal s3 ls

The response should display the date, time, and name of the bucket, confirming its creation.

Verify Using LocalStack Desktop
For a visual confirmation, you can use LocalStack Desktop. After all, seeing is believing! 😊

Open the LocalStack Desktop application.
Look for your active container in the container list.
Select the container
At the top center of the application, you’ll see four buttons. Hover over the last button to reveal its name: Resource Browser.
Click Resource Browser, and a list of supported AWS services will appear.
Locate S3 in the list and select it.
Choose your region from the bottom-right corner of the screen.
Refresh the view using the button at the top-right corner. You should now see your created bucket listed.

Congratulations! 🎉 You’ve just created an S3 bucket without needing an AWS account — pretty amazing, right? 😊

Next Steps

Now that your bucket is ready, let's test it by uploading a file to verify that it works as expected. We are going to create a simple python script to interact with out s3 bucket using the boto3 package.

1. Create your script file in the same directory localstack where your virtual environment was created:

touch base.py

2. Import required libraries:

import boto3
import logging
from io import BytesIO
from botocore.exceptions import ClientError

3. Configure the logger module:

logging.basicConfig(
    level=logging.DEBUG,  # Set the minimum log level (DEBUG, INFO, WARNING, etc.)
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",  # Log format
)

logger = logging.getLogger(__name__)

4. Define Configuration Variables:

AWS_ACCESS_KEY_ID = "test"
AWS_SECRET_ACCESS_KEY = "test"
S3_BUCKET_NAME = "my-new-bucket"
LOCALSTACK_HOST = "http://localhost:4566"  # Default LocalStack endpoint

The AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables are needed to create the client with boto3 but their values are not really important in this situation so you can assign any random value to them. The value assigned to the S3_BUCKET_NAME variable should be the actual name of the bucket you created above. If this is wrong, you'll get this error:

botocore.errorfactory.NoSuchBucket: An error occurred (NoSuchBucket) when calling the PutObject operation: The specified bucket does not exist

Finally, ensure the LOCALSTACK_HOST variable is be set to your LocalStack endpoint url.

5. Create the S3 Client:
To run a sanity check, let's try to create a new boto3 client and use that to list out s3 buckets.

def create_S3_client():
    s3_client = boto3.client(
        "s3",
        aws_access_key_id=AWS_ACCESS_KEY_ID,
        aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
        endpoint_url=LOCALSTACK_HOST,  # Point to LocalStack endpoint
    )
    return s3_client

def main():
    s3Client = create_S3_client()
    response = s3Client.list_buckets()
    print("Buckets:", response["Buckets"])

main()

Run the script using python3 base.py. Your response should contain a List of your created buckets, in this case it should contain only one item , an object with the Name and CreationDate of the bucket. now that we have validated this. Let's go ahead and finish up the python script.

6. Create the upload method:
We will be uploading an image so please move any jpg image of your choice into the localstack directory where the base.py file is also located. And change the name of the image to file.jpg

def upload_to_s3(file_bytes, filename, mimetype, object_name=None):
    """
    Uploads a file to an S3 bucket

    :param file_bytes: Bytes object of the file to be uploaded
    :param filename: Name of the file
    :param mimetype: MIME type of the file
    :param object_name: Name of the object in the bucket

    :return: True if the file was uploaded, else False
    """

    s3_client = create_S3_client()

    if object_name is None:
        object_name = filename

    try:
        # Wrap the bytes object in a BytesIO object
        file_obj = BytesIO(file_bytes)

        # Upload the file object to S3 bucket
        response = s3_client.upload_fileobj(
            file_obj, S3_BUCKET_NAME, object_name, ExtraArgs={"ContentType": mimetype}
        )
        logger.info(f"{object_name} uploaded to {S3_BUCKET_NAME} bucket")
        logger.info(response)
        return True
    except ClientError as e:
        logger.error(e)
        logger.exception(e)
        return False

7. Read File Data:

def read_file():
    file_bytes = None
    filename = None
    mimetype = None
    with open("file.jpg", "rb") as file:
        file_bytes = file.read()
        filename = f"images/{file.name}"
        mimetype = "image/jpeg"

    return file_bytes, filename, mimetype

Note: By setting the file name like this above f"images/{file.name}" means our file will be uploaded into the images/ directory in the s3 bucket and if it does not exist it will first be created.

8. Create the main method

def main():
    file_bytes, filename, mimetype = read_file()

    status = upload_to_s3(file_bytes, filename, mimetype)

    if status:
        logger.info("File uploaded successfully!")
    else:
        logger.error("File upload failed.")

if __name__ == "__main__":
    main()

The final code should look like this:

import boto3
import logging
from io import BytesIO
from botocore.exceptions import ClientError

logging.basicConfig(
    level=logging.DEBUG,  # Set the minimum log level (DEBUG, INFO, WARNING, etc.)
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",  # Log format
)

logger = logging.getLogger(__name__)

AWS_ACCESS_KEY_ID = "tester"
AWS_SECRET_ACCESS_KEY = "test"
S3_BUCKET_NAME = "my-new-bucket"
LOCALSTACK_HOST = "http://localhost:4566"  # Default LocalStack endpoint


def upload_to_s3(file_bytes, filename, mimetype, object_name=None):
    """
    Uploads a file to an S3 bucket

    :param file_bytes: Bytes object of the file to be uploaded
    :param filename: Name of the file
    :param mimetype: MIME type of the file
    :param object_name: Name of the object in the bucket

    :return: True if the file was uploaded, else False
    """

    s3_client = create_S3_client()

    if object_name is None:
        object_name = filename

    try:
        # Wrap the bytes object in a BytesIO object
        file_obj = BytesIO(file_bytes)

        # Upload the file object to S3 bucket
        response = s3_client.upload_fileobj(
            file_obj, S3_BUCKET_NAME, object_name, ExtraArgs={"ContentType": mimetype}
        )
        logger.info(f"{object_name} uploaded to {S3_BUCKET_NAME} bucket")
        logger.info(response)
        return True
    except ClientError as e:
        logger.error(e)
        logger.exception(e)
        return False


def create_S3_client():
    s3_client = boto3.client(
        "s3",
        aws_access_key_id=AWS_ACCESS_KEY_ID,
        aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
        endpoint_url=LOCALSTACK_HOST,  # Point to LocalStack endpoint
    )
    return s3_client


def read_file():
    file_bytes = None
    filename = None
    mimetype = None
    with open("file.jpg", "rb") as file:
        file_bytes = file.read()
        filename = f"images/{file.name}"
        mimetype = "image/jpeg"

    return file_bytes, filename, mimetype


def main():
    file_bytes, filename, mimetype = read_file()

    status = upload_to_s3(file_bytes, filename, mimetype)

    if status:
        logger.info("File uploaded successfully!")
    else:
        logger.error("File upload failed.")


if __name__ == "__main__":
    main()

9. Run the script:
Run the script using:

python3 base.py

If your file is uploaded successfully you should see this in your logs.

10. Verify Upload:
Now that you’ve uploaded your file to the S3 bucket my-new-bucket, let’s verify that the file exists..

Option1 - Verify via the CLI:
Run the following command in your terminal:

awslocal s3 ls s3://my-new-bucket/images/

This will return a list of all files in the images/ directory of the my-new-bucket bucket. You should see file.jpg in the response, similar to:

2025-01-07 12:00:00       12345 file.jpg

Option2 - Verify via LocalStack Desktop:

Open LocalStack Desktop and navigate to the S3 service.
Select the bucket my-new-bucket.
Refresh the view, and you should see the images/ directory. Inside, you’ll find your file.jpg file.
To double-check, click on the file row to download it to your local machine. Open the file to ensure it matches the original image you uploaded.

Congratulations! 🎉
You’ve successfully created an S3 bucket, uploaded a file, and verified its existence—all without needing an AWS account. I hope you’ve experienced your wow moments already! This guide demonstrates how simple, straightforward, and fast it is to work with AWS services on your local machine using LocalStack.

With LocalStack, you can truly keep local development local, saving time and resources while ensuring a smoother development workflow.

In the next part of this series, I’ll show you how to mock AWS Lambda functions locally using the LocalStack platform. Stay tuned — it’s going to be another exciting dive into the world of local AWS development! 😊

If you have any questions, feel free to drop them as a comment or send me a message on LinkedIn and I'll ensure I respond as quickly as I can. Ciao 👋

Simplifying Local AWS Development with LocalStack

Faruq Abdulsalam — Tue, 07 Jan 2025 09:02:04 +0000

So far in my career, I have developed several noteworthy full-stack applications utilizing AWS services, with the applications themselves hosted on AWS. Often, I’ve had to set up a local demo account on AWS to leverage several services in free-tier mode during development. These services include S3 for data storage, Cognito for authentication, API Gateway, AWS Lambda, Elastic Container Registry, Certificate Manager, Simple Email Service (SES), and Simple Notification Service (SNS), among many others. The list is endless.

To test how the application would behave in a live environment, I’d also need to set up EC2 instances (app servers), CloudWatch for alarms and logs, and EventBridge for task scheduling. This made me question whether this can still be called "local development." After all, we’re relying on live AWS services, and we can’t fully validate how everything will work until it’s in the staging environment.

On a recent project, we had several Lambda functions that needed to be validated before deployment. To make testing easier, we mocked the API Gateway using the FastAPI framework to invoke the Lambda functions. This approach allowed us to test each Lambda function during development. However, we ran into a frustrating bug (the infamous "But it works fine on my system" issue). The cause? Our local API Gateway environment had different settings from the cloud environment. I genuinely believe that if we had an option to mock the AWS services exactly as they are, we could have avoided this issue.

Recently, I discovered LocalStack, a cloud development platform that addresses exactly the challenges I’ve been facing. To my surprise, it’s been around since 2016. That made me feel like I’d been living under a rock, but at the same time, there’s so much to explore in the world of tech. It’s impossible to know every tool out there — but staying curious and exploring the ones you need as you come across them is key.

Since discovering LocalStack, I’ve been testing out its services, and I can honestly say it’s been a series of "wow" moments. "Wow, that was fast," "Wow, I can actually do this locally," and "Wow, this could really save me time!" It’s been exciting to see how LocalStack can replicate AWS services locally with such ease.

Because of this, I’ve decided to create a series that walks through how to use each service offered by LocalStack. By combining the steps in this series with LocalStack’s documentation, I believe you’ll be able to truly keep your local development, well, local (pun intended!). This way, you can work more efficiently and avoid the pitfalls I’ve encountered.

How to Integrate Next-Auth with Your Next.js Application

Faruq Abdulsalam — Tue, 16 Jul 2024 12:50:07 +0000

Recently, I migrated a frontend application from an older version of Next.js to Next.js 14. During this process, I decided to upgrade the session handling approach. After extensive research, I chose to use NextAuth.js, now known as Auth.js.

In the application, server-side authentication with AWS Cognito is utilized, and I wanted to maintain this setup. The goal was to seamlessly integrate authentication tokens and user data retrieved from successful authentications into Auth.js, ensuring session availability across the entire app and enabling authorization enforcement for different pages.

In this article, I'll guide you through the process of successfully integrating Auth.js with your Next.js application using the app router. We will cover both the credentials (email and password) approach and Google social login.

Note: Next-Auth v5 is still in beta mode, so I wouldn't fully recommend integrating it into a production application just yet. However, the final decision is up to you.

Prerequisites

Familiarity with the basics of React.js
Brief experience with Next.js app router
Basic understanding of Typescript, as we'll be using Next.js with TypeScript

You don't need to have prior experience with Next-Auth.js (now Auth.js) to follow this article.

Note: For the rest of the article, I’ll be using next-auth and Auth.js interchangeably.

Let's get started!!

1. Create your Next.js application
Start by generating a new Next.js application:

npx create-next-app@latest

After running the command above, follow the prompts, accepting the defaults for TypeScript and Tailwind CSS as we'll be using TypeScript and will apply minor styling with Tailwind. Also choose Yes for the import alias and accept the default alias configuration.

2. Install Auth.js
Install the latest version of auth.js using npm or yarn

npm install next-auth@beta

yarn add next-auth@beta

3. Generate and Configure Your Environment Variables
Create a .env.local file and add your Auth.js secret. Auth.js uses this for encryption of your JWTs and cookies.

touch .env.local

Generate the secret string by running any of the two commands:

# Linux/Mac terminal
openssl rand -base64 33

# Alternatively, use `auth` to generate the secret
npx auth secret

Add the generated secret to your .env.local file:

AUTH_SECRET="your-secret"

You can escape running into major issues when you don't set this in your development environment. But it is compulsory to set it in the production environment.

You should also add your backend URL here

NEXT_PUBLIC_BASE_URL="your-backend-url"

4. Create your interface and types.
To manage your types effectively, create a new directory named types in your root directory (or in your /src directory if you are using it), then inside it, add two new files: login.ts and user.ts.

├── app
├── public
├── types
│   ├── login.ts
│   ├── user.ts
├── .env.local
└── ...

Your app directory should look something like this with some other files and folders which are not shown here.

login.ts
Add the following types for different authentication scenarios:

type CredentialsType = {
  username: string;
  password: string;
};

type SocialCredentialsType = {
  auth_code: string;
};

export type { CredentialsType, SocialCredentialsType };

CredentialsType: Defines the structure for email and password login credentials.
SocialCredentialsType: Defines the structure for social login credentials, specifically for Google authentication.

user.ts
Define interface and type for user data to manage session details:

interface UserType {
  id: string;
  name: string;
  email: string;
  avatar: string;
  premiumSubscription: boolean;
  accessToken: string;
  refreshToken: string;
  subId: string;
}

type UserResponseType = {
  id: string;
  name: string;
  email: string;
  avatar: string;
  premium_subscription: boolean;
  access_token: string;
  refresh_token: string;
  sub_id: string;
};

export type { UserType, UserResponseType };

UserType: Interface specifying the expected properties for user session management.
UserResponseType: Type specifying the format of user data as received from the backend.

5. Create your Auth.js configuration.
Create a new file named auth.ts in your root directory. If you are using the src/ directory approach, place the file directly within the src/ folder.

├── app
├── public
├── types
│   ├── login.ts
│   ├── user.ts
├── .env.local
├── auth.ts
└── ...

auth.ts
At the top of the file import the necessary libraries and types for
configuring Auth.js.

// library imports
import NextAuth from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";

// types imports
import type { NextAuthConfig, Session, User } from "next-auth";
import type { UserType, UserResponseType } from "@/types/user";
import { AdapterUser } from "next-auth/adapters";
import { CredentialsType, SocialCredentialsType } from "@/types/login";
import { JWT } from "next-auth/jwt";

Next, we have to modify some of the types in the next-auth library with some of our own properties.

declare module "next-auth" {
  interface User extends UserType {}
}

declare module "next-auth/adapters" {
  interface AdapterUser extends UserType {}
}

declare module "next-auth/jwt" {
  interface JWT extends UserType {}
}

Here, we used the TypeScript module augmentation feature to extend the User, AdapterUser, JWT interfaces from NextAuth with properties defined in UserType from our user.ts file. This ensures that our custom user properties are recognized throughout the Auth.js configuration.

Next we declare authOptions object which we'll use to initialize NextAuth at the end.

const authOptions = {
  providers: [
// Add authentication providers here (e.g., CredentialsProvider, GoogleProvider)
  ],
  callbacks: {
 // Add custom authentication callbacks here (e.g., signIn, signOut, jwt, session)
  },
  pages: {
// Customize authentication-related pages (e.g., signIn, error)
  },
  session: {
// Configure session options (e.g., JWT settings, session management)
  },
} satisfies NextAuthConfig;

export const { handlers, auth, signIn, signOut } = NextAuth(authOptions);

A.providers: accepts an array of providers such as CredentialsProvider, GoogleProvider, e.t.c.

B.callbacks: specifies custom callback functions that can be triggered at various points in the authentication process.

C.pages: auth.js has default authentication-related pages for signIn, error, signOut e.t.c. But in this block , we can override it with our customized pages by specifying their paths.

D.session: Configures session options, such as how sessions are handled and stored. e.g jwt or database approach

Finally, we initialize NextAuth with the authOptions configuration and destructure the returned methods (handlers, auth, signIn, signOut) for use in our application.
- handlers: Middleware for handling NextAuth requests.
- auth: A universal method to interact with Auth.js in your Next.js app.
- signIn: Method to trigger sign-in.
- signOut: Method to trigger sign-out.

The code in the auth.ts file should look like this now

// library imports
import NextAuth from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";

// types imports
import type { NextAuthConfig, Session, User } from "next-auth";
import type { UserType, UserResponseType } from "@/types/user";
import { AdapterUser } from "next-auth/adapters";
import { CredentialsType, SocialCredentialsType } from "@/types/login";
import { JWT } from "next-auth/jwt";

declare module "next-auth" {
  interface User extends UserType {}
}

declare module "next-auth/adapters" {
  interface AdapterUser extends UserType {}
}

declare module "next-auth/jwt" {
  interface JWT extends UserType {}
}

const authOptions = {
  providers: [
  ],
  callbacks: {
  },
  pages: {
  },
  session: {
  },
} satisfies NextAuthConfig;

export const { handlers, auth, signIn, signOut } = NextAuth(authOptions);

Now, let's complete the authOptions object with the necessary values.

A. providers:
We will use CredentialsProvider for handling authentication on the server side by making requests to our server URL. We will set it up twice: once for email and password login, and once for social login with Google. To distinguish between the two, we specify unique id values.

providers: [
    CredentialsProvider({
      id: "credentials",
      name: "Credentials",
      authorize: async (credentials) => {
        try {
          const user = await fetchUser(
            `${process.env.NEXT_PUBLIC_BASE_URL}/auth/login`,
            {
              username:
                typeof credentials.username === "string"
                  ? credentials.username
                  : "",
              password:
                typeof credentials.password === "string"
                  ? credentials.password
                  : "",
            }
          );

          return user ? createUser(user) : null;
        } catch (error) {
          console.error("Error during authentication", error);
          return null;
        }
      },
    }),
    CredentialsProvider({
      id: "social",
      name: "Custom Social Login",
      authorize: async (credentials) => {
        try {
          const user = await fetchUser(
            `${process.env.NEXT_PUBLIC_BASE_URL}/auth/social_login`,
            {
              auth_code:
                typeof credentials.authCode === "string"
                  ? credentials.authCode
                  : "",
            }
          );

          return user ? createUser(user) : null;
        } catch (error) {
          console.error("Error during authentication", error);
          return null;
        }
      },
    }),
  ],

Email and Password Login:
- The first CredentialsProvider is configured for email and password login.
- It makes a request to ${process.env.NEXT_PUBLIC_BASE_URL}/auth/login with the provided credentials via the fetchUser function(replace this URL with your backend URL).
- If a user is found, createUser(user) is called to format the user data.
Social Login with Google:
- The second CredentialsProvider is configured for social login using Google.
- It makes a request to ${process.env.NEXT_PUBLIC_BASE_URL}/auth/social_login with the provided auth code via the fetchUser function(replace this URL with your backend URL).
- If a user is found, createUser(user) is called to format the user data.

Each provider has a unique id to distinguish between the two methods of authentication.

By using CredentialsProvider twice with different id values, we can manage multiple authentication methods seamlessly.

Here are the definitions of the fetchUser and createUser functions:

// Function to authenticate and fetch user details
async function fetchUser(
  url: string,
  body: CredentialsType | SocialCredentialsType
) {
  try {
    const res = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    const user = await res.json();

    if (res.ok && user) {
      return user;
    } else {
      console.error(`Failed to fetch user: ${res.status} ${res.statusText}`);
      return null;
    }
  } catch (error) {
    console.error(`Error during fetch: ${error}`);
    return null;
  }
}

// Function to create a user object
function createUser(user: UserResponseType) {
  const userObject: UserType = {
    id: user.id,
    name: user.name,
    email: user.email,
    avatar: user.avatar,
    premiumSubscription: user.premium_subscription,
    accessToken: user.access_token,
    refreshToken: "", //add subId from the auth service here
    subId: "", // add refresh token here
  };

  return userObject;
}

B. callbacks:
The callbacks section allows us to customize the behavior of the authentication process. Here, we’ll add two async functions: jwt and session.

callbacks: {
    async jwt({ token, user }: { token: JWT; user: User }) {
      // Add the user properties to the token after signing in
      if (user) {
        token.id = user.id as string;
        token.avatar = user.avatar;
        token.name = user.name;
        token.email = user.email;
        token.premiumSubscription = user.premiumSubscription;
        token.accessToken = user.accessToken;
        token.subId = user.subId;
        token.refreshToken = user.refreshToken;
      }
      return token;
    },
    async session({ session, token }: { session: Session; token: JWT }) {
      // Create a user object with token properties
      const userObject: AdapterUser = {
        id: token.id,
        avatar: token.avatar,
        name: token.name,
        premiumSubscription: token.premiumSubscription,
        accessToken: token.accessToken,
        subId: token.subId,
        refreshToken: token.refreshToken,
        email: token.email ? token.email : "", // Ensure email is not undefined
        emailVerified: null, // Required property, set to null if not used
      };

      // Add the user object to the session
      session.user = userObject;

      return session;
    },
  },

jwt callback:
- The jwt function is called during the authentication process to add user properties to the JWT token. When a user signs in, their properties, such as id, avatar, name, email, accessToken, subId, and refreshToken, are added to the token. This token is then used to securely manage user sessions.
session callback:
- The session function is called whenever a session is accessed to add user data to the session object. A user object is created using the properties from the token. This user object is then added to the session, ensuring that user data is available whenever the session is accessed. The email property is ensured to be a string, and emailVerified is set to null if not used.

C. pages:
In the pages section of the authOptions object, we define paths to our custom pages that will override the default authentication-related pages provided by Auth.js. This allows us to customize the user experience for specific authentication actions.

  pages: {
    signIn: "/auth/login", // Custom sign-in page
    // error: "/auth/error", // Custom error page
  },

signIn: Specifies the path to a custom sign-in page. By setting this to /auth/login, we direct users to our custom login page instead of the default Auth.js sign-in page.
error: Optionally, we can specify a custom error page. This is commented out here, but if we wanted to use a custom error page, we could set its path like so: error: /auth/error.

D. session:
In the session section of the authOptions object, we specify how sessions should be managed. In this case, we are using JSON Web Tokens (JWT) as the session strategy.

  session: {
    strategy: "jwt",
  },

strategy: By setting this to "jwt", we ensure that sessions are managed using JSON Web Tokens. This means that session data is encoded and stored in a JWT, which is then sent to the client.

Here is what the entire file should look like now

// library imports
import NextAuth from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";

// types imports
import type { NextAuthConfig, Session, User } from "next-auth";
import type { UserType, UserResponseType } from "@/types/user";
import { AdapterUser } from "next-auth/adapters";
import { CredentialsType, SocialCredentialsType } from "@/types/login";
import { JWT } from "next-auth/jwt";

// Modify NextAuth types with custom properties
declare module "next-auth" {
  interface User extends UserType {}
}

declare module "next-auth/adapters" {
  interface AdapterUser extends UserType {}
}

declare module "next-auth/jwt" {
  interface JWT extends UserType {}
}

const authOptions = {
  providers: [
    CredentialsProvider({
      id: "credentials",
      name: "Credentials",
      authorize: async (credentials) => {
        try {
          const user = await fetchUser(
            `${process.env.NEXT_PUBLIC_BASE_URL}/auth/login`,
            {
              username:
                typeof credentials.username === "string"
                  ? credentials.username
                  : "",
              password:
                typeof credentials.password === "string"
                  ? credentials.password
                  : "",
            }
          );

          return user ? createUser(user) : null;
        } catch (error) {
          console.error("Error during authentication", error);
          return null;
        }
      },
    }),
    CredentialsProvider({
      id: "social",
      name: "Custom Social Login",
      authorize: async (credentials) => {
        try {
          const user = await fetchUser(
            `${process.env.NEXT_PUBLIC_BASE_URL}/auth/social_login`,
            {
              auth_code:
                typeof credentials.authCode === "string"
                  ? credentials.authCode
                  : "",
            }
          );

          return user ? createUser(user) : null;
        } catch (error) {
          console.error("Error during authentication", error);
          return null;
        }
      },
    }),
  ],
  callbacks: {
    async jwt({ token, user }: { token: JWT; user: User }) {
      // Add the user properties to the token after signing in
      if (user) {
        token.id = user.id as string;
        token.avatar = user.avatar;
        token.name = user.name;
        token.email = user.email;
        token.premiumSubscription = user.premiumSubscription;
        token.accessToken = user.accessToken;
        token.subId = user.subId;
        token.refreshToken = user.refreshToken;
      }
      return token;
    },
    async session({ session, token }: { session: Session; token: JWT }) {
      // Create a user object with token properties
      const userObject: AdapterUser = {
        id: token.id,
        avatar: token.avatar,
        name: token.name,
        premiumSubscription: token.premiumSubscription,
        accessToken: token.accessToken,
        subId: token.subId,
        refreshToken: token.refreshToken,
        email: token.email ? token.email : "", // Ensure email is not undefined
        emailVerified: null, // Required property, set to null if not used
      };

      // Add the user object to the session
      session.user = userObject;

      return session;
    },
  },
  pages: {
    signIn: "/auth/login", // Custom sign-in page
    // error: "/auth/error", // Custom error page
  },
  session: {
    strategy: "jwt",
  },
} satisfies NextAuthConfig;

// Function to authenticate and fetch user details
async function fetchUser(
  url: string,
  body: CredentialsType | SocialCredentialsType
) {
  try {
    const res = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    const user = await res.json();

    if (res.ok && user) {
      return user;
    } else {
      console.error(`Failed to fetch user: ${res.status} ${res.statusText}`);
      return null;
    }
  } catch (error) {
    console.error(`Error during fetch: ${error}`);
    return null;
  }
}

// Function to create a user object
function createUser(user: UserResponseType) {
  const userObject: UserType = {
    id: user.id,
    name: user.name,
    email: user.email,
    avatar: user.avatar,
    premiumSubscription: user.premium_subscription,
    accessToken: user.access_token,
    refreshToken: "", //add subId from the auth service here
    subId: "", // add refresh token here
  };

  return userObject;
}

export const { handlers, auth, signIn, signOut } = NextAuth(authOptions);

6. Utilize the configuration in the Next.js API route.
To integrate the NextAuth configuration into a Next.js API route, follow these steps:

Create a new file named route.ts in the app directory at the following path:

├── app
│   ├── api
│   │   ├── auth
│   │   │   ├── [...nextauth]
│   │   │   │   ├──  route.ts
├── auth.ts
└── ...

In the route.ts file, add the following lines of code:

// library imports
import { handlers } from "@/auth";

export const { GET, POST } = handlers;

At the top, we import the handlers object from auth.ts, then destructure it to extract the GET and POST methods and exports them. When a request is made to the /api/auth endpoint, the route.ts file delegates the request to the appropriate handler (GET or POST) provided by NextAuth. These handlers manage the authentication logic, session management, and other related tasks based on the configuration we defined earlier in auth.ts.

We are done with setting up Auth.js. Now let's use the magic we created and see it in action

7. Using Auth.js in our Next.js Application
Now that we have completed the setup for Auth.js, it's time to see it in action. We'll integrate authentication into our application by creating email and password sign-in, social login and protected pages.

A. Create the authentication components
First, create a components directory in the root directory of your app (in the src/ directory if you are using this approach). Then add auth and protected directories in it.

Create a new file named login.tsx in the components/auth directory and a new file named profile.tsx in the components/profile directory:

├── app
├── components
│   ├── auth
│   │   ├── login.tsx
│   ├── profile
│   │   ├── profile.tsx

login.tsx: Here we will add the following code to create a sign-in form and a google login button.

"use client";

// library imports
import React, { useState, useEffect } from "react";
import Link from "next/link";
import { useSearchParams } from "next/navigation";

export default function SignIn() {
  const searchParams = useSearchParams();
  const googleLogin = "Your google login url which will contain your client id and redirectURI";

  const [username, setUsername] = useState("");
  const [password, setPassword] = useState("");
  const [authenticated, setAuthenticated] = useState(false);
  const [error, setError] = useState("");

  useEffect(() => {
    if (authenticated) {
      // Redirect to previous page or home page
      const next = searchParams.get("next") || "/";
      window.location.href = next;
    }
  }, [authenticated]);

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    try {
      const res = await fetch("/api/login", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ username, password, type: "credentials" }),
      });

      if (res.ok) {
        setAuthenticated(true);
      } else {
        // handle error state here
        setError("Invalid credentials");
      }
    } catch (error) {
      // handle error state here
      console.error("Error during sign-in", error);
      setError("Internal server error");
    }
  };

return (
    <div className="mx-auto w-[200px] h-full border-red-100">
      <div>
        <p className="text-xl w-full flex justify-center mt-3 mb-5">Sign In</p>
        <form onSubmit={handleSubmit}>
          <label>
            Username:
            <input
              type="text"
              className="w-full rounded-sm"
              value={username}
              onChange={(e) => setUsername(e.target.value)}
            />
          </label>
          <label>
            Password:
            <input
              className="w-full rounded-sm"
              type="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
            />
          </label>
          <button
            className="w-full flex justify-center bg-teal-500 text-white mt-3 rounded-md"
            type="submit"
          >
            Sign In
          </button>
          {error && <p style={{ color: "red" }}>{error}</p>}
        </form>
      </div>
      <div className="my-2">
        <div className="flex justify-center"> or </div>
      </div>
      <div className="w-full bg-red-700 rounded-md mb-2">
        <Link href={googleLogin} className="flex ">
          <p className="w-full text-white flex justify-center">
            Sign in with Google
          </p>
        </Link>
      </div>
    </div>
  );
}

We'll send a POST request to an API route (/api/login) to handle authentication. If the login is successful, the user will be redirected to the next page or home page. If the Sign in with Google button is clicked, the user will be redirected to the google-login page

Next, we will create the /api/login endpoint to handle the authentication logic on the server side. Create a new folder named login in the app/api directory and create a route.ts file in it.

├── app
│   ├── api
│   │   ├── auth
│   │   ├── login
│   │   │   ├── route.ts
├── components
├── auth.ts
└── ...

route.ts:

// library imports
import { NextResponse, NextRequest } from "next/server";

// internal imports
import { signIn } from "@/auth";

export async function POST(req: NextRequest, res: NextResponse) {
  const data = await req.json();
  const { username, password, type } = data;

  try {
    const result =
      type === "credentials"
        ? await signIn("credentials", { redirect: false, username, password })
        : await signIn("social", { redirect: false, authCode: username });

    // handle the result of the sign-in attempt
    if (!result || result.error) {
      return NextResponse.json({ error: "Invalid credentials" });
    } else {
      return NextResponse.json({ success: true });
    }
  } catch (error) {
    console.error("Error during sign-in", error);
    return NextResponse.error();
  }
}

Here, we handle authentication for both credentials and social login types. Based on the type of login, we call the signIn function with either credentials (username and password) or social login (auth_code).

Next, we will create the social login page. Create a new file named socialAuth.tsx in the components/auth directory.

├── app
├── components
│   ├── auth
│   │   ├── login.tsx
│   │   ├── socialAuth.tsx
│   ├── profile

socialAuth.tsx: Add the following code to socialAuth.tsx.

"use client";

// library imports
import React, { useState, useEffect } from "react";
import Link from "next/link";
import { useRouter, useSearchParams } from "next/navigation";

export default function SocialAuth() {
  const googleLogin =
    "Your google login url which will contain your client id and redirectURI";

  const router = useRouter();
  const searchParams = useSearchParams();

  const [authSuccess, setAuthSuccess] = useState(true);
  const [tokenStatus, setTokenStatus] = useState(false);

  useEffect(() => {
    // check query string for authentication code
    if (authSuccess || tokenStatus) {
      const url = window.location.href;
      const code = url.match(/\?code=(.*)/);
      if (!tokenStatus && authSuccess) {
        if (code) {
          authenticateUser(code[1]);
        } else {
          router.push("/auth/login");
        }
      } else if (tokenStatus) {
        // Redirect to previous page or home page
        const next = searchParams.get("next") || "/";
        router.push(next);
      } else {
        router.push("/auth/login");
      }
    }
  }, [tokenStatus, authSuccess]);

  const authenticateUser = async (code: string) => {
    try {
      const res = await fetch("/api/login", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ username: code, type: "social" }),
      });

      if (res.ok) {
        setTokenStatus(true);
      } else {
        // handle error state here
        setAuthSuccess(false);
      }
    } catch (error) {
      // handle error state here
      setAuthSuccess(false);
    }
  };

  return (
    <>
      <div>
        {authSuccess ? (
          <div>
            <h1>Authenticating...</h1>
          </div>
        ) : (
          <div>
            <h1>
              {" "}
              An error occurred while attempting to authenticate your account
              with Google{" "}
            </h1>

            <div>
              <div>
                <Link href={googleLogin}>Please try again</Link>
              </div>
            </div>
          </div>
        )}
      </div>
    </>
  );
}

This ensures that users can authenticate via social login providers like Google and handles the authentication flow smoothly.

B. Create the Authentication Pages
Next, let's create the custom sign-in and social login pages that utilize the components we created above.

Create a new directory called auth in the app/ directory. Inside auth, create folders named login and social, and then add a page.tsx file in both folders.

├── app
│   ├── auth
│   │   ├── login
│   │   │   ├── page.tsx
│   │   ├── social
│   │   │   ├── page.tsx

In login/page.tsx, add the following code:

//component imports
import SignIn from "@/components/auth/login";

export default function LoginPage() {
  return <SignIn />;
}

In social/page.tsx, add the following code:

//component imports
import SocialAuth from "@/components/auth/socialAuth";

export default function SocialAuthPage() {
  return <SocialAuth />;
}

We are now set with authentication, and you can confirm the state of what we have done so far.

Attempt to navigate to this url http://localhost:3000/api/auth/signin. You should be redirected back to the custom sign-in page. This redirection occurs because of the URL path we specified in the pages section of our authOptions object while setting up the configuration in auth.ts.

B. Create protected page
The final step is to create a protected page that users cannot access unless they are authenticated.

-profile.tsx
Let's add the code below to our empty file profile.tsx in the components directory.

"use client";

// library imports
import React, { useState, useEffect } from "react";
import { useSession } from "next-auth/react";
import { useRouter, usePathname } from "next/navigation";

export default function Profile() {
  const router = useRouter();
  const pathname = usePathname();

  const { data: session } = useSession();

  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL;

  const [loadingProfile, setLoadingProfile] = useState(false);

  useEffect(() => {
    if (session?.user?.accessToken) {
      // fetch user profile if access token is available
      getUserProfile(session.user.accessToken);
    } else {
      // Redirect to `/login` if no access token or no session
      router.push("/auth/login?next=" + pathname);
    }
  }, []);

  const getUserProfile = (token: string) => {
    setLoadingProfile(true);
    fetch(`${baseUrl}/auth/user_profile`, {
      headers: { Authorization: "Bearer " + token },
    })
      .then((response) => {
        setLoadingProfile(false);
      })
      .catch((error) => {
        // handle error here
        console.error(error);
      });
  };

  return (
    <>
      {" "}
      {loadingProfile ? (
        <p>Loading...</p>
      ) : (
        <div>
          <p>User Profile</p>
          <p>Name: {session?.user?.name}</p>
          <p>Email: {session?.user?.email}</p>
        </div>
      )}
    </>
  );
}

Here we use the useSession hook to check if a user session with an access token exists. If the token is present , we go ahead and make a call to the backend route /auth/user_profile . In my case i have a protected route in the backend which an unauthenticated user cannot access without a token. While waiting for the profile data to load, a loading indicator is displayed. Once loaded, the component displays the user's name and email. If there is no active session or access token, it redirects the user back to the login page to authenticate.

Finally, we create the page which utilizes the profile.tsx component above. Create a new folder in the app directory named profile and in it a page.tsx file.

page.tsx:

// library imports
import { SessionProvider } from "next-auth/react";

// internal imports
import { auth } from "@/auth";

//component imports
import Profile from "@/components/profile/profile";

export default async function ProfilePage() {
  const session = await auth();

  return (
    <SessionProvider session={session}>
      <Profile />
    </SessionProvider>
  );
}

First we import the SessionProvider component from next-auth/react to serve as a context provider for managing the user session state throughout the application. Additionally, we import the auth method from auth.js. Since this operation requires asynchronous behavior, we utilize a server-side component, using await to fetch the session using the auth method. Subsequently, we pass this session object obtained from auth to the SessionProvider component which acts as a wrapper around the Profile component. We have to wrap the component with Session Provider here if we want the session to be accessible within profile.tsx using the useSession hook, similar to how we handled authentication state above.

Now if we try to access the /profile route, we would get redirected to the /auth/login page since we are not logged in. Once we login, we would be redirected back to the profile page, where we can see our user data.

Congratulations , you have successfully integrated your next js application using the app router with auth.js v5.

You might have noticed that in the profile.tsx component, we check the session for a token and then redirect the user back to the login page if the token is not present. This means that Next.js already starts rendering our page before redirecting to the login page if the token is absent. If you pay attention, you'll also notice this in the UI.

An alternative to this approach is to use middleware to handle authentication. Next.js has a middleware feature that is triggered when a user attempts to access a route. We can use this to protect our authenticated routes. This way, the protected page is not rendered if an unauthenticated user attempts to access it, as the middleware intercepts the request and redirects the user to the login route. This ensures we have a central location to check the session and redirect users if they are unauthenticated, thereby improving the user experience with the UI.

8. Adding a Middleware
Create a new file called middleware.ts in your root directory. If you are using the src/ directory approach, place the file directly within the src/ folder.

├── app
├── public
├── types
├── .env.local
├── auth.ts
├── middleware.ts
└── ...

-middleware.ts
In the file add the following lines of code:

import { NextResponse } from "next/server";
import { auth } from "@/auth";

export default auth((req) => {
  const currentPath = req.nextUrl.pathname;

  // Redirect to login page if user is not authenticated
  if (!req.auth) {
    return NextResponse.redirect(
      new URL(`/auth/login?next=${currentPath}`, req.url)
    );
  }
});

// Manage list of protected routes
export const config = {
  matcher: ["/profile/:path*", "/another-protected-route/:path*"],
};

This middleware checks if the user is authenticated before allowing access to specified routes. If the user is not authenticated, they are redirected to the login page. The config object defines the routes that should trigger this middleware, ensuring that only protected routes are affected.

By setting up this middleware, you centralize the authentication logic, making your codebase cleaner and more maintainable as your application grows.

Note: In my application, I have several authenticated and unauthenticated routes, which is why I am not triggering the middleware with all requests and instead maintaining a protected routes list. The little downside to this is that you have to manage a list of all your protected routes. This might end up becoming a long list and could become difficult to manage, or someone might implement a protected page and forget to update the middleware. If your base path is the only unprotected route, your job will be much easier.

It's been a long ride, but we have finally come to the end of this tutorial. With what you have learned, I believe you can seamlessly integrate Auth.js v5 into your `next.js application.

Here is the link to the github repo for this project. Cheers!!!

If you have any questions, feel free to drop them as a comment or send me a message on LinkedIn and I'll ensure I respond as quickly as I can. Ciao 👋

How to add login authentication to a Flask and React application.

Faruq Abdulsalam — Tue, 21 Dec 2021 08:14:51 +0000

In flask, adding authentication has been made quite easy with the @login_required decorator in the flask extension Flask-login. I have an article on how to add basic authentication to your flask application that you can read up on here

However, since you will be working with API endpoints you can't use the approach above because the @login_required decorator redirects to the application to an HTML page when it discovers a user that is not authenticated trying to access a protected page. This defeats the idea of creating API endpoints as APIs are only designed to return data in json format.

In this part of the series, you'll be learning how to add authentication to the connected React and Flask application you built in the previous part of the series. Authentication will be done with the flask extension: flask-jwt-extended

Prerequisites

1) Beginner-level understanding of the flask framework. If you are new to Flask you can check out my article on how to set up your flask project and use it with the jinja template engine.

2) I strongly advise you to read the previous article. You can also get the files in the Github repo.

3) Familiarity with the basics of ReactJs. You will be making use of the useState hook, fetching data from API endpoints using axios and also using react-router-dom to handle routing of components.

Let's get started!!

Flask Backend

Installing the flask extension.

Navigate into the backend directory and run:

pip install flask-jwt-extended

note: If you cloned the repo, you don't need to run the command above, just set up your flask application with the instructions in the README.md file.

base.py

You'll be adding authentication to the /profile API endpoint created in the previous tutorial. Navigate to the base.py script you created in the backend directory of your application to create the token(login) and logout API endpoints.

token(login) API endpoint

import json
from flask import Flask, request, jsonify
from datetime import datetime, timedelta, timezone
from flask_jwt_extended import create_access_token,get_jwt,get_jwt_identity, \
                               unset_jwt_cookies, jwt_required, JWTManager


api = Flask(__name__)

api.config["JWT_SECRET_KEY"] = "please-remember-to-change-me"
jwt = JWTManager(api)

@api.route('/token', methods=["POST"])
def create_token():
    email = request.json.get("email", None)
    password = request.json.get("password", None)
    if email != "test" or password != "test":
        return {"msg": "Wrong email or password"}, 401

    access_token = create_access_token(identity=email)
    response = {"access_token":access_token}
    return response

@api.route('/profile')
def my_profile():
    response_body = {
        "name": "Nagato",
        "about" :"Hello! I'm a full stack developer that loves python and javascript"
    }

    return response_body

Let's go through the code above:

First, the required functions are imported from the installed flask_jwt_extended extension.

from flask_jwt_extended import create_access_token,get_jwt,get_jwt_identity, \
                               unset_jwt_cookies, jwt_required, JWTManager

Next, the flask application instance is configured with the JWT secret key then passed as an argument to the JWTManager function and assigned to the jwt variable.

api.config["JWT_SECRET_KEY"] = "please-remember-to-change-me"
jwt = JWTManager(api)

The token API endpoint will have a POST request method. Whenever the user submits a login request, the email and password are extracted and compared with the hardcoded email(test) and password(test). Please note that in an ideal scenario you are going to compare the extracted login details with data in your database.

If the login details are not correct, the error message Wrong email or password with the status code 401 which means UNAUTHORIZED Error is sent back to the user.

return {"msg": "Wrong email or password"}, 401

Else if the login details are confirmed to be correct, an access token is created for that particular email address by assigning the email to the identity variable. Finally, the token is returned to the user.

access_token = create_access_token(identity=email)

response = {"access_token":access_token}
return response

To test this, start your backend server with

npm run start-backend

Please note that the command above was specified in the package.json file in the react frontend. This was done in the previous part of the series. If you have not checked it out yet, please head there so you can learn how to set it up. However if you have already cloned the repo, let's proceed.

Next, open up postman and send a POST request to this API endpoint:

http://127.0.0.1:5000/token

You'll get a 500 internal server error 👇

Check your terminal and you'll see the error as well 👇

AttributeError: 'NoneType' object has no attribute 'get' the error occurred because you did not specify the login details when you made the POST request to the API endpoint thus a None value was passed as an argument to the request.json.get function.

Return to POSTMAN and pass the login details along with the POST request.

Please ensure you adjust your settings as circled in the image above.

After making the request you should get your access token in the form:

"access_token":"your access token will be here"

You can try to pass in a wrong email or password to see the 401 UNAUTHORIZED error

Logout API endpoint

@api.route("/logout", methods=["POST"])
def logout():
    response = jsonify({"msg": "logout successful"})
    unset_jwt_cookies(response)
    return response

When the logout API endpoint is called, response is passed to the unset_jwt_cookies function which deletes the cookies containing the access token for the user and finally returns the success message to the user.

Head over to Postman once again and make a POST request to the logout API endpoint:

http://127.0.0.1:5000/logout

You should get the response below 👇

Refreshing tokens

The generated token always has a lifespan after which it expires. To ensure that this does not happen while the user is logged in, you have to create a function that refreshes the token when it is close to the end of its lifespan.

First, specify the lifespan for your generated tokens and add it as a new configuration for your application.
Note:You can change the time to suit your application.

api.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)

Then, create the function below 👇, above the create_token function:

@api.after_request
def refresh_expiring_jwts(response):
    try:
        exp_timestamp = get_jwt()["exp"]
        now = datetime.now(timezone.utc)
        target_timestamp = datetime.timestamp(now + timedelta(minutes=30))
        if target_timestamp > exp_timestamp:
            access_token = create_access_token(identity=get_jwt_identity())
            data = response.get_json()
            if type(data) is dict:
                data["access_token"] = access_token 
                response.data = json.dumps(data)
        return response
    except (RuntimeError, KeyError):
        # Case where there is not a valid JWT. Just return the original respone
        return response

The after_request decorator ensures that the refresh_expiring_jwts function runs after a request has been made to the protected API endpoint /profile. The function takes as an argument, the response from the /profile API call.

Then, the current expiry timestamp for the user's token is obtained and compared with the specified timestamp for the token which is set at 30 minutes. You can change this as well.

If the expiry timestamp for the user's token happens to be 30minutes away from expiration, the token for that user is changed to a new one with the specified 1hr lifespan, and the new token is appended to the response returned to the user. But if the token is not close to expiration, the original response is sent to the user.

To conclude the backend setup, you need to add the @jwt_required() decorator to the my_profile function to prevent unauthenticated users from making requests to the API endpoint. But first, test the /profile API endpoint by making a GET request to the URL below using Postman:

http://127.0.0.1:5000/profile

You should still get the json form of the dictionary created in the last article.

Next, add the @jwt_required() decorator

@api.route('/profile')
@jwt_required() #new line
def my_profile():
    response_body = {
        "name": "Nagato",
        "about" :"Hello! I'm a full stack developer that loves python and javascript"
    }

    return response_body

and try to make the API request to the /profile endpoint using the URL above. You'll get a 401 UNAUTHORIZED error because the token was absent when you made the request.

After the user logs in and gets the assigned token, the token needs to be sent with each call the user makes to the API endpoints in the backend as an Authorization Header in this format:

Authorization: Bearer <access_token>

Before you head over to the frontend, you can also test this on Postman by adding the user's token to the Authorization header before you call the protected \profile API endpoint.

Make a POST request to the endpoint below to get your token and copy it out.

http://127.0.0.1:5000/token

Next, add the authorization header key with your token as its value and then send the GET request, you should get a json response containing the dictionary with your name and about_me info.

Congratulations you have successfully added authentication to your API endpoint. After the changes and additions, this should be the final look of the base.py script.

import json
from flask import Flask, request, jsonify
from datetime import datetime, timedelta, timezone
from flask_jwt_extended import create_access_token,get_jwt,get_jwt_identity, \
                               unset_jwt_cookies, jwt_required, JWTManager


api = Flask(__name__)

api.config["JWT_SECRET_KEY"] = "please-remember-to-change-me"
api.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
jwt = JWTManager(api)

@api.after_request
def refresh_expiring_jwts(response):
    try:
        exp_timestamp = get_jwt()["exp"]
        now = datetime.now(timezone.utc)
        target_timestamp = datetime.timestamp(now + timedelta(minutes=30))
        if target_timestamp > exp_timestamp:
            access_token = create_access_token(identity=get_jwt_identity())
            data = response.get_json()
            if type(data) is dict:
                data["access_token"] = access_token 
                response.data = json.dumps(data)
        return response
    except (RuntimeError, KeyError):
        # Case where there is not a valid JWT. Just return the original respone
        return response

@api.route('/token', methods=["POST"])
def create_token():
    email = request.json.get("email", None)
    password = request.json.get("password", None)
    if email != "test" or password != "test":
        return {"msg": "Wrong email or password"}, 401

    access_token = create_access_token(identity=email)
    response = {"access_token":access_token}
    return response

@api.route("/logout", methods=["POST"])
def logout():
    response = jsonify({"msg": "logout successful"})
    unset_jwt_cookies(response)
    return response

@api.route('/profile')
@jwt_required()
def my_profile():
    response_body = {
        "name": "Nagato",
        "about" :"Hello! I'm a full stack developer that loves python and javascript"
    }

    return response_body

Now you can head over to the react frontend where you'll be making the API endpoint calls.

React Frontend

In the last article, you only had to make a few changes to the App.js file. But this time around major changes will be made and new components will also be created.

In the frontend, a Login component that will hold the login page will be created. This component will be rendered anytime it notices that an unauthenticated user is trying to access a page that contains a protected API endpoint. This will ensure that any request made to the backend has a token appended to it.

To start with, create a new directory components in the src directory and in it, four new components Login.js, useToken.js, Header.js and Profile.js. Then navigate back to the base directory and install react-router-dom before you go into the components:

npm install react-router-dom

Storage of token in the frontend

The token generated from the backend needs to be stored in your web browser after you log in. Presently, that is not the case. Whenever a user refreshes his browser page, the token gets deleted and the user would be prompted to log in once again.

To fix this, you'll need to make use of web storage objects: localStorage or sessionStorage. You can read more on that here.

i)sessionStorage: The user's token gets stored in the tab currently opened in the browser. If the user refreshes the page, the token is still retained. However, if the user opens a new tab to the same page in the web browser, the token won't reflect on that page as the new tab doesn't share the same storage with the previous one. Thus, the user would be prompted to log in again.

To see this in action, open any website of your choice and open up the Developer tools menu with the Inspect Element or Inspect option by right-clicking on any page in your browser. You can also see the web storage under the Application section.

Open up your console and store an object sample in the web storage using the sessionStorage function.

sessionStorage.setItem('test', 53)

Then to get the value 53 assigned to the key test above run:

sessionStorage.getItem('test')

Refresh the page and run the getItem function again, you'll still get the value from the storage.

Now, open the link to the same page you just worked with, in a new tab, and try to access the stored object value via the console:

sessionStorage.getItem('test')

You'll get a null value because the current tab doesn't have access to the storage of the previous tab.

note: while carrying out all the tests above, keep an eye on the changes occurring in the web storage section above your console.

ii)localStorage: Here, the user's token get's stored in universal storage that can be accessed by all tabs and browser windows. The token is still retained even if the user refreshes or closes the page, creates a new tab or window, or restarts the browser entirely.

localStorage.setItem('test', 333)

Then to get the assigned value 333:

localStorage.getItem('test')

Try to run the duplicate test done above, you'll notice that you can access the value from the duplicated page. You can also create a new browser window, open any page of the same website and try to access the value set above. You'll notice that you still have access to it. That is the beauty of using localStorage, it ensures that the user only needs to log in once and they can easily navigate to any page on the website.

Whenever you are done, you can delete the object from the storage using:

localStorage.removeItem("token")

useToken.js

Now you need to replicate what was done above in your react code. Open the useToken component.

import { useState } from 'react';

function useToken() {

  function getToken() {
    const userToken = localStorage.getItem('token');
    return userToken && userToken
  }

  const [token, setToken] = useState(getToken());

  function saveToken(userToken) {
    localStorage.setItem('token', userToken);
    setToken(userToken);
  };

  function removeToken() {
    localStorage.removeItem("token");
    setToken(null);
  }

  return {
    setToken: saveToken,
    token,
    removeToken
  }

}

export default useToken;

With the tests you carried out in the console, the functions created in the useToken component should be easy to understand.

The getToken function is used to retrieve the token stored in the localStorage and only returns a token if it exists hence the use of the && conditional operator.

The useState hook is used to handle the state of the token variable which will contain the value of the token. This ensures that the react application always reloads when any of the functions are called. Such that when a user logs in and the token is stored or when the user logs out, the application also becomes aware that a change has occurred in the web storage of your browser and hence reacts accordingly by either redirecting to the page the user wants to access or returning to the login page once the user logs out.

The saveToken function handles the storage of the token obtained when the user logs in and the setToken function in it updates the state of the token variable with the token passed as an argument to the saveToken function.

The removeToken function deletes the token from the local storage and returns the token back to the null state whenever it gets called.

Finally, the saveToken function assigned as a value to the setToken variable, the value of the token itself and the removeToken function are all returned as the result of calling the useToken function.

App.js

I told you that you'll be making major changes right? 😜. Clean up App.js; all the code that was added the last time will be moved into the Profile component.

import { BrowserRouter, Route, Routes } from 'react-router-dom'
import Login from './components/Login'
import Profile from './components/Profile'
import Header from './components/Header'
import useToken from './components/useToken'
import './App.css'

function App() {
  const { token, removeToken, setToken } = useToken();

  return (
    <BrowserRouter>
      <div className="App">
        <Header token={removeToken}/>
        {!token && token!=="" &&token!== undefined?  
        <Login setToken={setToken} />
        :(
          <>
            <Routes>
              <Route exact path="/profile" element={<Profile token={token} setToken={setToken}/>}></Route>
            </Routes>
          </>
        )}
      </div>
    </BrowserRouter>
  );
}

export default App;

At the top of the file, the BrowserRouter, Route, Routes functions that will be used to handle URL routing for the profile component are imported from the installed react-router-dom package. The other created components are also imported from the components folder.

In the App function, the value object returned when the useToken function is called is destructured and the values are assigned to the token, removeToken and setToken variables respectively.

const { token, removeToken, setToken } = useToken();

Next, the BrowserRouter function is made the parent component and in it, the Header component is placed with the removeToken function passed as an argument which is called prop in react.

<Header token={removeToken}/>

Then the javascript conditional ternary operator is used to ensure that the user must have a token before having access to the profile component. If the user doesn't have a token, the Login component is rendered with the setToken function passed as an argument. Else if the user already has a token, the Profile component with the URL path /profile is rendered and displayed to the user.

You can read more on how to use React Router here

Now, you need to create the Login, Header, and Profile functions in your Login, Header, and Profile component files respectively.

Login.js

import { useState } from 'react';
import axios from "axios";

function Login(props) {

    const [loginForm, setloginForm] = useState({
      email: "",
      password: ""
    })

    function logMeIn(event) {
      axios({
        method: "POST",
        url:"/token",
        data:{
          email: loginForm.email,
          password: loginForm.password
         }
      })
      .then((response) => {
        props.setToken(response.data.access_token)
      }).catch((error) => {
        if (error.response) {
          console.log(error.response)
          console.log(error.response.status)
          console.log(error.response.headers)
          }
      })

      setloginForm(({
        email: "",
        password: ""}))

      event.preventDefault()
    }

    function handleChange(event) { 
      const {value, name} = event.target
      setloginForm(prevNote => ({
          ...prevNote, [name]: value})
      )}

    return (
      <div>
        <h1>Login</h1>
          <form className="login">
            <input onChange={handleChange} 
                  type="email"
                  text={loginForm.email} 
                  name="email" 
                  placeholder="Email" 
                  value={loginForm.email} />
            <input onChange={handleChange} 
                  type="password"
                  text={loginForm.password} 
                  name="password" 
                  placeholder="Password" 
                  value={loginForm.password} />

          <button onClick={logMeIn}>Submit</button>
        </form>
      </div>
    );
}

export default Login;

The code above should be easy to understand, the summary of what it does is to use the login details provided by the user to make a POST request to the /token API endpoint in the backend which then returns the user's token and the token is stored in the local web storage using the setToken function passed as a prop to the Login function.

Header.js

import logo from '../logo.svg'
import axios from "axios";

function Header(props) {

  function logMeOut() {
    axios({
      method: "POST",
      url:"/logout",
    })
    .then((response) => {
       props.token()
    }).catch((error) => {
      if (error.response) {
        console.log(error.response)
        console.log(error.response.status)
        console.log(error.response.headers)
        }
    })}

    return(
        <header className="App-header">
            <img src={logo} className="App-logo" alt="logo" />
            <button onClick={logMeOut}> 
                Logout
            </button>
        </header>
    )
}

export default Header;

Once the user clicks on the Logout button, a POST request is made to the /logout API endpoint, and the cookies in which the user's JWToken is stored are cleared on the backend. The Axios response function is used to call the removeToken function which deletes the token stored in the local web storage. Now, if the user tries to access the /profile page, the user gets redirected to the login page.

Profile.js

import { useState } from 'react'
import axios from "axios";

function Profile(props) {

  const [profileData, setProfileData] = useState(null)
  function getData() {
    axios({
      method: "GET",
      url:"/profile",
      headers: {
        Authorization: 'Bearer ' + props.token
      }
    })
    .then((response) => {
      const res =response.data
      res.access_token && props.setToken(res.access_token)
      setProfileData(({
        profile_name: res.name,
        about_me: res.about}))
    }).catch((error) => {
      if (error.response) {
        console.log(error.response)
        console.log(error.response.status)
        console.log(error.response.headers)
        }
    })}

  return (
    <div className="Profile">

        <p>To get your profile details: </p><button onClick={getData}>Click me</button>
        {profileData && <div>
              <p>Profile name: {profileData.profile_name}</p>
              <p>About me: {profileData.about_me}</p>
            </div>
        }

    </div>
  );
}

export default Profile;

The piece of code previously in App.js was moved here. This contains the protected endpoint \profile. A GET request method is sent to the endpoint whenever the Click me button is clicked and it responds with the user's details.

For the user to be able to access the data of the \profile API endpoint, an Authorization header that contains the token must be added to the axios GET request.

headers: {
        Authorization: 'Bearer ' + props.token
      }

If the response contains an access token, this means that the current token is near expiration and the server has created a new token. So the token stored in the local storage is updated with the newly generated token.

res.access_token && props.setToken(res.access_token)

App.css

You also need to make a change to the CSS style for the header. On line 16 you'll see the style for the header component .App-header. Comment out or delete the /* min-height: 100vh; */ code so your application can end up looking like 👇:

Now to test your application, start the backend server by running the script below

npm run start-backend

followed by :

npm start

Then navigate to the http://localhost:3000/profile URL in your web browser and you'll be prompted to login since the page is protected. I hope you still remember the login details: email:test and password:test. You can also open up localStorage under the Application section in Developer tools to monitor the token as it gets stored and deleted.

It's been a long ride, but we have finally come to the end of this tutorial. With what you have learned, I believe you can easily authenticate your flask plus react applications. Congratulations on the new knowledge you just acquired.

If you have any questions, feel free to drop them as a comment or send me a message on Linkedin or Twitter and I'll ensure I respond as quickly as I can. Ciao 👋

How to connect Flask to ReactJs

Faruq Abdulsalam — Tue, 14 Dec 2021 08:41:26 +0000

Building web applications with the Flask framework and the inbuilt jinja template is cool but hooking your backend to a react frontend(which I believe we all love 😉) is much more interesting. In this tutorial, you are going to be taken through the easy steps you need to take to connect your Flask backend to a React frontend.

Prerequisite

1) Beginner level understanding of the flask framework. If you are new to Flask you can check out my article on how to set up your flask project and use it with the jinja template engine here.

2) Familiarity with the basics of ReactJs. You will be making use of the useState hook and also fetching data from API using axios.

Let's get started.

Project directory

Create the project directory where your application will be stored and then navigate into it.

mkdir project

cd project

React frontend setup

Create the frontend react application by running:

npx create-react-app flask_react

Move into the flask_react directory

cd flask_react

and then start the frontend application by running

npm start

The default react application page should pop up in your browser; if it does not, copy and open the link below in your browser.

http://localhost:3000

Flask backend setup

Create a new directory in your base directory

mkdir backend

then navigate into it

cd backend

If you have been following my Building a web application with Flask series you should know the next thing that needs to be created. Yes, a virtual environment. Did you happen to get that right? 😀

Virtual environment

It is recommended to always create a virtual environment before you start your project. This helps you to separate the packages you use in this application from other applications; any change you make here won't affect the same package in another application on your system. To create a virtual environment on your system; run this command:

For mac/unix users: python3 -m venv env
For windows users: py -m venv env

After creating the environment, activate it by running :

For mac/unix users: source env/bin/activate
For windows users: .\env\Scripts\activate

Installing Flask

Now that you have your environment up and running, you can go ahead and install Flask

pip install flask

The next thing is to register the script in an environment file.

pip install python-dotenv

After successful installation, create the .flaskenv file in the backend directory created above.

touch .flaskenv

Please note that the preceding . is very important. If you name your file just flaskenv, any environment variable you'll put in it won't be read.

Now put your environment variables in the .flaskenv file:

FLASK_APP=base.py
FLASK_ENV=development

The application environment is set to development mode so you can easily debug your application and the base.py file which will contain your flask application will be created in the next section.

If the above approach is not used, you would need to keep on exporting your environment variables using export FLASK_APP=base.py and export FLASK_ENV=development whenever you restart your terminal window.

Note: To ensure that the focus of this article doesn't deviate, I'll be making the flask backend structure simple. If you want to build bigger projects you definitely have to create a better folder structure for your application. You can check out my articles on Getting started with Flask and Building a Todo List Application with Flask if you need to learn how to create a folder structure for larger projects.

base.py

Create a new file base.py in the backend directory where the .flaskenv directory is also located.

touch base.py

Your folder structure should currently look like 👇

Inside the base.py script create a simple API that returns your name and info about you:

from flask import Flask

api = Flask(__name__)

@api.route('/profile')
def my_profile():
    response_body = {
        "name": "Nagato",
        "about" :"Hello! I'm a full stack developer that loves python and javascript"
    }

    return response_body

The code above contains a simple API which would be called by the react front end to get the response_body dictionary.

You might have noticed two things:
i) the GET http method is not specified here. This is because, by default, view functions in flask accept GET requests only.
ii) the response_body dictionary being returned at the end of the function is not being passed as an argument to the popular jsonify function like this jsonify(response_body). This is because view functions in Flask can return a dictionary, which Flask then turns to JSON format.

The backend has been successfully set up, you can test this by running your application.

flask run

Then navigate to the url http://127.0.0.1:5000/profile.You should see the dictionary response_body rendered in JSON format.

You could also use postman to confirm this and you'll still get the same result.

If you want to push your code to source control. Don't forget to add your env and __pycache__ folders to the gitignore file in the base directory.

backend/env
backend/__pycache__

Connecting the API endpoint(/profile) to the react frontend

Now you can return to the base directory where the react frontend is located.

cd ..

Install the `axios` library:

Note: You can choose to use either axios or fetch to make HTTP requests. However, in this article, the axios library will be used to make requests to the API endpoints you built earlier on.

npm install axios

package.json

Open the package.json file and add the proxy below the "private": true, line so it ends up like 👇.

  "name": "flask_react",
  "version": "0.1.0",
  "private": true,
  "proxy": "http://localhost:5000", //newline

By doing this, you will be able to use relative paths when you are making the API requests. Instead of making use of http://localhost:5000/profile you can simply make use of /profile.

Note: The default url which is normally used to access flask applications in the browser is http://127.0.0.1:5000 but http://localhost:5000 was used above as the value to the proxy key. Don't be confused, they are both the same. You can read more on that here

Don't close the package.json file yet. There is something cool you can add as well. You know that whenever your react server is started and you make any change in a file and you save it, the server restarts so that the new change can reflect right?. You can also add that feature to your flask backend application. This is another advantage of connecting react to flask 😎.

Under the scripts section add another key and value.
"start-backend": "cd backend && env/bin/flask run --no-debugger", so it ends up looking like 👇

  "scripts": {
    "start": "react-scripts start",
    "start-backend": "cd backend && env/bin/flask run --no-debugger", //new line
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

Now you can start your backend server with npm run start-backend. This executes the command passed as its value in the package.json file. It navigates into the env directory in your backend directory and executes the flask run command.

The --no-debugger option is also passed here to disable the browser-based debugger as the Flask backend only serves as a server that holds the API endpoint.

app.js

Here, you'll be making the call to the API endpoint in the flask backend server. After the changes, the app.js file will look exactly like 👇

import { useState } from 'react'
import axios from "axios";
import logo from './logo.svg';
import './App.css';

function App() {

   // new line start
  const [profileData, setProfileData] = useState(null)

  function getData() {
    axios({
      method: "GET",
      url:"/profile",
    })
    .then((response) => {
      const res =response.data
      setProfileData(({
        profile_name: res.name,
        about_me: res.about}))
    }).catch((error) => {
      if (error.response) {
        console.log(error.response)
        console.log(error.response.status)
        console.log(error.response.headers)
        }
    })}
    //end of new line 

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>

        {/* new line start*/}
        <p>To get your profile details: </p><button onClick={getData}>Click me</button>
        {profileData && <div>
              <p>Profile name: {profileData.profile_name}</p>
              <p>About me: {profileData.about_me}</p>
            </div>
        }
         {/* end of new line */}
      </header>
    </div>
  );
}

export default App;

Now let's go through the new lines of code added to the app.js file.

At the top of the file, the useState hook and axios module are both imported.

Then inside the function named App the useState hook is used to control the state of the profileData variable.

The getData function handles the API calls. It contains the axios module which is used to send a GET request to the API endpoint(\profile) on the backend which responds with the jsonified format of the dictionary declared in the view function.

Next, the setProfileData function updates the state of profileData by assigning the data in the json response to profile_name and about_me.

The getData function is only called when the click me button is pressed.

Finally && is used as a conditional operator, to avoid getting an error. profileData is going to be assigned an initial null state when the application first loads so if you try to access profileData.profile_name or profileData.about_me you get an error message.

TypeError: Cannot read properties of null (reading 'profile_name')

Hence the need for the && conditional operator, so that the application only knows of the existence of the profileData.profile_name and profileData.about_me codes when the value of profileData has changed from null to containing the response data from the API call.

You don't need to make changes to any other file in the base directory. The work on the frontend part of the application is now complete. Now you can go ahead and test it:

Step1: start your backend server using npm run start-backend
note this command can be run while you are in any directory; be it the base directory(flask_react) or the flask directory (backend)

Step2: start your react server using npm start

Now click on the click me button to make the API call and get the name and about_me data from the backend.

Voila!! you have successfully connected your flask backend to your react frontend. Now I am sure you can build small API endpoints in your flask backend and call the endpoints from your react frontend.

If you have any questions, feel free to drop them as a comment or send me a message on Linkedin or Twitter and I'll ensure I respond as quickly as I can.

Incase you are a Django lover, you would definitely love to connect it to React as well. You can check out my article on How to connect Django to ReactJs to learn how to go about that. Ciao 👋

Uploading media files to your Flask application

Faruq Abdulsalam — Tue, 30 Nov 2021 09:30:32 +0000

In this tutorial, you'll be taken through the easy steps required to upload a media file to your Flask applications.

Prerequisite

We'll be building on the simple application built in part 1 of this series. I believe you can recreate that setup by yourself now.

If you are new to the series, do well to check out part 1 before proceeding. Let's get started!!!

Configurations

The first thing to do is to create the Configuration class that will handle the following

i) location where the uploaded files will be stored
ii) secret key
iii) allowed file extensions
iv) limiting the size of the file that can be uploaded.

static/uploads directory

Create a directory called static in the core directory. Then create an uploads directory in the static directory. This is where your media files will be stored. You can choose to change the name of the directories if you choose to.

.env

Since we'll be dealing with forms. We need to ensure that we provide our secret key as an environmental variable to ensure that the application doesn't become vulnerable through the form post requests.

Create a .env file in the root repository and place your secret key in it

SECRET_KEY = put-your-own-secret-secret-key-here

config.py

Create a config.py file in the base directory

import os
from dotenv import load_dotenv 

load_dotenv()
basedir = os.path.abspath(os.path.dirname(__file__))

class Config(object):
    SECRET_KEY = os.environ.get('SECRET_KEY')
    UPLOAD_FOLDER = os.path.join(basedir, 'core/static/uploads')
    ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif'}
    MAX_CONTENT_LENGTH = 16 * 1024 * 1024

The secret key is loaded from the environment file .env and assigned to the SECRET_KEY variable.

Next, the value assigned to the UPLOAD_FOLDER variable is the path to the uploads folder created earlier on.

The allowed extensions coupled with the maximum content length(size) of media files that can be uploaded are also specified here.

init.py

Next, you need to import the Configuration class and configure the app variable with it. This assigns all the configuration settings to the application.

from flask import Flask
from config import Config

app = Flask(__name__)
app.config.from_object(Config)

from core import views

views.py

from flask import render_template,flash,request,redirect
from core import app
from werkzeug.utils import secure_filename
from config import Config
import os

@app.route('/', methods=['POST','GET'])
def index():
    greeting="Hello there, Ace"

    if request.method == 'POST':
        file = request.files['file']
        if file.filename == '':
            flash('No file was selected')
            return redirect(request.url)
        elif file and allowed_file(file.filename):
            filename = secure_filename(file.filename)
            file.save(os.path.join(Config.UPLOAD_FOLDER, filename))
            flash('Image has been successfully uploaded')
            return redirect('/')
        else:
            flash('Allowed media types are - png, jpg, jpeg, gif')
            return redirect(request.url)
    else:
        return render_template('index.html', greet=greeting)


def allowed_file(filename):
    return '.' in filename and \
           filename.rsplit('.', 1)[1].lower() in Config.ALLOWED_EXTENSIONS

Let's go through the code above:

The os module for path configuration, Configuration class, and flash function to display messages, request method & redirect function to handle page redirects are all imported at the top of the file.

The secure_filename function is required to handle unclear or malicious file names. It ensures that the file names are always clean and flat.

The default HTTP method is GET so the POST method needs to be added to the app.route function.

After confirming that a POST request method was made, request.files['file'] is used to confirm that the data of a file input with the name attribute of file is included in the submitted form data and an error message is flashed if the condition evaluates to false

The submitted data which is the uploaded media name + extension type is then passed as an argument to the allowed_file function where it is split into name of file and extension. The allowed_file function ensures that only a file with the permitted extension is processed and uploaded.

Next, the secure_filename function is called with the filename as an argument. It helps to ensure that a file with a malicious filename is not saved in the application.

If all the checks are passed successfully, the uploaded media file is saved in the specified folder which in your case should be static/uploads.

index.html

To test the file upload functionality, you need to make an upgrade to the index html page as well.

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Test HTML</title>
    </head>
    <body>
        <h1>{{greet}}</h1>

        {% with messages = get_flashed_messages() %}
            {% if messages %}
                <ul class="flashes">
                {% for message in messages %}
                    <li>{{ message }}</li>
                {% endfor %}
                </ul>
            {% endif %}
        {% endwith %}

        <form method= "post" enctype=multipart/form-data>
            <input type=file name=file>
            <input type=submit value=Upload>
        </form>
    </body>
</html>

The newly added lines surrounded in curly braces allow the flash messages to be rendered on the page in case an error occurs while uploading the file.

The enctype attribute assigned the value
multipart/form-data is always used when files need to be uploaded via the form.

The file input has the name attribute, file which the view function uses to confirm that a file was submitted together with the form.

You can now run your application to test the whole setup:

flask run

You'll notice that when you try to submit the form without selecting an image, you get an error message notifying you that No file was selected.

Then when you finally do the right thing; and you upload an image, you get the message Image has been successfully uploaded. Now go to the folder that was created in the static directory core\static\uploads. You'll see the image file you just uploaded.

Congratulations, we have come to the end of the tutorial. I believe you can now easily set up your flask applications to have file upload functionality. You can choose to make changes to the setup such as changing the allowed extensions, maximum content length, or the location of your uploads directory. Cheers!!

Bonus: To use the image file, you can store the filename in your database after the image has been stored in the uploads folder, then Query the db for the filename and pass it to the render function.

    <img src="{{ url_for('static', filename=upload/'your filename') }}">

When the page is rendered, your filename variable then gets replaced with the result of the db query for the stored filename and, your image is displayed.

If you have any questions, feel free to drop them as a comment or send me a message on Linkedin or Twitter and I'll ensure I respond as quickly as I can. Ciao 👋

Adding authentication to a Flask application

Faruq Abdulsalam — Tue, 23 Nov 2021 09:38:54 +0000

Welcome to the last part of the series. Here, you'll learn how to add authentication to your flask application. The todo application built in part 2 will be used here. So if you come across this part first, do well to check out parts 1 and 2.

Let's get started!!

Install the flask extension Flask-login:

pip install flask-login

Next, open the__init__.py file in the core directory. Import the Login Manager class from the installed package and initialise the application with it.

from flask import Flask
from config import Config
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager #new line

app = Flask(__name__)
app.config.from_object(Config)
db = SQLAlchemy(app)
migrate = Migrate(app, db)
login = LoginManager(app) #new line

auth blueprint

The authentication section will be created as a mini-application as well. So create a new directory auth in the core directory and add the following files: __init__.py, forms.py, models.py, and views.py.

Remember that this is going to be an application on its own so you need to create a templates folder in the auth directory as well. Create a new folder auth in it and within it create two files login.html and register.html.

auth blueprint

Let's start with the __init__.py script. This will be set up the same way as that of the task blueprint.

from flask import Blueprint

auth = Blueprint('auth', __name__, template_folder='templates')

from . import views

models.py

from .. import db
from werkzeug.security import generate_password_hash, check_password_hash
from .. import login
from flask_login import UserMixin
from ..models import Todo

class User(UserMixin, db.Model):
    __tablename__ = 'user'
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(64), index=True, unique=True)
    email = db.Column(db.String(120), index=True, unique=True)
    password_hash = db.Column(db.String(128))
    todo = db.relationship('Todo', backref='author', lazy='dynamic')

    def __repr__(self):
        return '<User {}>'.format(self.username)

    def set_password(self, password):
        self.password_hash = generate_password_hash(password)

    def check_password(self, password):
        return check_password_hash(self.password_hash, password)

@login.user_loader
def load_user(id):
    return User.query.get(int(id))

Then set up the User model for the database using the UserMixin class.

The todo field is initialized with db.relationship which is like a one-to-many relationship. The first argument Todo passed here is the many side of the relationship and the one is author. This will create an author field in every todo you create.

The relationship established here just means that there will be many posts linked to just one user. This will ensure that one user doesn't have access to the to-do list of another user.

The load_user function stores the id of the user so that the user can navigate to another page while logged in. If this is absent, whenever the user navigates to a new page, the user will be prompted to log in again.

forms.py

from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, BooleanField, SubmitField, ValidationError
from wtforms.validators import DataRequired, Length, Email, EqualTo
from .models import User

class LoginForm(FlaskForm):
    email = StringField('Email', validators=[DataRequired(), Length(1, 64),
                                       Email()])
    password = PasswordField('Password', validators=[DataRequired()])
    remember_me = BooleanField('Remember Me')
    submit = SubmitField('Sign In')

class RegistrationForm(FlaskForm):
    username = StringField('Username', validators=[DataRequired()])
    email = StringField('Email', validators=[DataRequired(), Email()])
    password = PasswordField('Password', validators=[DataRequired()])
    password2 = PasswordField(
        'Repeat Password', validators=[DataRequired(), EqualTo('password')])
    submit = SubmitField('Register')

    def validate_username(self, username):
        user = User.query.filter_by(username=username.data).first()
        if user is not None:
            raise ValidationError('Username already in use.')

    def validate_email(self, email):
        user = User.query.filter_by(email=email.data).first()
        if user is not None:
            raise ValidationError('Email already registered.')

You need to install the package that'll validate the email address submitted by the user.

pip install email_validator

Create the Login and Registration forms and import the User model for validation purposes. This checks whether the email or username is already in the database and raises an error if a similar email or username is found.

views.py

from flask import render_template, flash, redirect, url_for, request
from flask_login import login_user, logout_user, login_required, \
    current_user
from . import auth
from .forms import RegistrationForm, LoginForm
from .models import User
from .. import db
from werkzeug.urls import url_parse

@auth.route('/register', methods=['GET', 'POST'])
def register():
    if current_user.is_authenticated:
        return redirect(url_for('task.tasks'))
    form = RegistrationForm()
    if form.validate_on_submit():
        user = User(username=form.username.data.lower(), email=form.email.data.lower())
        user.set_password(form.password.data)
        db.session.add(user)
        db.session.commit()
        flash('Congratulations, you are now a registered user!')
        return redirect(url_for('auth.login'))
    return render_template('auth/register.html', title='Register', form=form)

@auth.route('/login', methods=['GET', 'POST'])
def login():
    nologin = False
    if current_user.is_authenticated:
        return redirect(url_for('task.tasks'))
    form = LoginForm()
    if form.validate_on_submit():
        user = User.query.filter_by(email=form.email.data.lower()).first()
        if user is None or not user.check_password(form.password.data):
            nologin = True
        else:
            login_user(user, remember=form.remember_me.data)
            next_page = request.args.get('next')
            if not next_page or url_parse(next_page).netloc != '':
                next_page = url_for('task.tasks')
            return redirect(next_page)
    return render_template('auth/login.html', title='Sign In', form=form, message=nologin)

@auth.route('/logout')
def logout():
    logout_user()
    return redirect(url_for('index'))

Let's go through each function:
i) Register: if the user navigates to the \register URL, the register function is executed and the first condition provided checks if the user is already logged in. Then the user gets redirected to the index page of the application if this evaluates to true. Else, the register page is loaded and the form is rendered. Upon submission, the form is validated and the user data is stored. Next, the user is redirected to the login page.
ii)Login: if the user navigates to the \login URL, the login function is executed and a similar process is repeated here.
iii)Logout: When the user clicks on the logout button and is redirected to the logout URL, the user gets logged out.

The HTML template files are written in the same format as the other template files in parts 1 and 2 so they are self-explanatory

login.html

{% extends "base.html" %}

{% block content %}


<a class="brand-logo" href="{{ url_for('index') }}">
    <img class="logo" src="{{ url_for('static', filename='Logo.svg') }}">
    <div class="brand-logo-name"><strong> ToDo </strong> </div>
</a>

<!-- Display login error message-->
{% if message %}
<div class="alert alert-warning" role="alert">
    <span class="closebtns" onclick="this.parentElement.style.display='none';">&times;</span>Invalid username or password
</div>
{% endif %}

<div class="login">
    <form action="" method="post" novalidate class="p-3 border border-2">
        {{ form.hidden_tag() }}
        <div class="Login-Header">
            <h4 class="mb-5">Login</h4>
        </div>
        <p>
            {{ form.email.label }}<br>
            {{ form.email(size=32) }}
            {% for error in form.email.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <p>
            {{ form.password.label }}<br>
            {{ form.password(size=32) }}
            {% for error in form.password.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <p>{{ form.remember_me() }} {{ form.remember_me.label }}</p>
        <div class="loginbtn">
            {{ form.submit(class="btn btn-primary mt-3") }}
        </div>
    </form>
    <div class=logged_in> 
        <span>Dont have an account yet?</span> 
        <a href="{{ url_for('auth.register') }}"> <i class="fa fa-hand-o-right" aria-hidden="true"></i>Register</a> 

    </div>
</div>
{% endblock %}

register.html

{% extends "base.html" %}

{% block content %}


<a class="brand-logo" href="{{ url_for('index') }}">
    <img class="logo" src="{{ url_for('static', filename='Logo.svg') }}">
    <div class="brand-logo-name"><strong> ToDo </strong> </div>
</a>

<div class="register">
    <form action="" method="post" class="p-3 border border-2">
        {{ form.hidden_tag() }}
        <div class="Register-Header">
            <h4 class="has-text-centered mb-5 is-size-3">Register</h4>
        </div>

        <p>
            {{ form.username.label(class="label") }}<br>
            {{ form.username(size=32) }}<br>
            {% for error in form.username.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <p>
            {{ form.email.label(class="label") }}<br>
            {{ form.email(size=64) }}<br>
            {% for error in form.email.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <p>
            {{ form.password.label(class="label") }}<br>
            {{ form.password(size=32) }}<br>
            {% for error in form.password.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <p>
            {{ form.password2.label(class="label") }}<br>
            {{ form.password2(size=32) }}<br>
            {% for error in form.password2.errors %}
            <span style="color: red;">[{{ error }}]</span>
            {% endfor %}
        </p>
        <div class="registerbtn">
            {{ form.submit(class="btn btn-primary mt-3") }}
        </div>
    </form>
    <div class="registered">
        <span>Already registered?</span> 
        <a href="{{ url_for('auth.login') }}"><i class="fa fa-hand-o-right" aria-hidden="true"></i>Login</a> 
    </div>
</div>
{% endblock %}

init.py

Finally, you need to register the auth blueprint in the __init__.py file in the core directory. Add the following lines of code above the task blueprint.

from flask import Flask
from config import Configuration
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager 

app = Flask(__name__)
app.config.from_object(Configuration)
db = SQLAlchemy(app)
migrate = Migrate(app, db)
login = LoginManager(app) 
login.login_view = 'auth.login' #new line


# blueprint for auth routes in our app #new blueprint
from .auth import auth as auth_blueprint
app.register_blueprint(auth_blueprint)

# blueprint for non-authentication parts of the app
from .task import task as task_blueprint
app.register_blueprint(task_blueprint)

from core import views, models

The path to the login view function is assigned to the initialised LoginManager class and the auth blueprint is registered with the application.

models.py (base)

Since you already established a relationship between the User model and Todo model. You need to head to the models.py file in the core directory and create the user_id field that'll be linked to the User model via a ForeignKey.

user_id = db.Column(db.Integer, db.ForeignKey('user.id'))

But the issue now is that SQLite database does not support dropping or altering columns. When you try to migrate and upgrade the db you get either a naming convention or ALTER of constraints error.

or

There are two ways you can solve this.
i) Delete the migrations folder and also the db file in your root directory. This is not advisable if you already have a lot of data in your db.
ii) Create a naming convention for all your database columns in the __init__.py file in the core directory. Solution can be found here

init.py

from flask import Flask
from config import Configuration
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager 
from sqlalchemy import MetaData #new line

app = Flask(__name__)
app.config.from_object(Configuration)
db = SQLAlchemy(app)

#new line
naming_convention = {
    "ix": 'ix_%(column_0_label)s',
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(column_0_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s",
}
db = SQLAlchemy(metadata=MetaData(naming_convention=naming_convention))

migrate = Migrate(app, db, render_as_batch=True) #new line
login = LoginManager(app)
login.login_view = 'auth.login'


# blueprint for auth routes in our app
from .auth import auth as auth_blueprint
app.register_blueprint(auth_blueprint)

# blueprint for non-authentication parts of the app
from .task import task as task_blueprint
app.register_blueprint(task_blueprint)

from core import views, models

Now run the following commands: flask db stamp head, flask db migrate and flask db upgrade to migrate all the changes to your db. The naming convention error should no longer exist.

views.py

The final step is to make changes to the task view function so that users can only view the page if they are logged in. Make the following changes to the views.py file in the task directory.

from flask import render_template, flash, redirect, url_for, request
from flask_login import login_required, current_user #new line
from .models import Category
from ..models import Todo
from . import task
from .forms import TaskForm
from .. import db
from datetime import datetime

@task.route('/create-task', methods=['GET', 'POST'])
@login_required #new line
def tasks():
    check= None
    user = current_user #new line
    todo= Todo.query.filter_by(author=user) #new line
    date= datetime.now()
    now= date.strftime("%Y-%m-%d")

    form= TaskForm()
    form.category.choices =[(category.id, category.name) for category in Category.query.all()]

    if request.method == "POST":
        if request.form.get('taskDelete') is not None:
            deleteTask = request.form.get('checkedbox')
            if deleteTask is not None:
                todo = Todo.query.filter_by(id=int(deleteTask)).one()
                db.session.delete(todo)
                db.session.commit()
                return redirect(url_for('task.tasks'))
            else:
                check = 'Please check-box of task to be deleted'

        elif form.validate_on_submit():
            selected= form.category.data
            category= Category.query.get(selected)
            todo = Todo(title=form.title.data, date=form.date.data, time= form.time.data, category= category.name, author=user) #new line
            db.session.add(todo)
            db.session.commit()
            flash('Congratulations, you just added a new note')
            return redirect(url_for('task.tasks'))

    return render_template('task/tasks.html', title='Create Tasks', form=form, todo=todo, DateNow=now, check=check)

Import the login_required function and also the current_user variable. Then assign the login_required function as a decorator to the task view function. The current logged in user is obtained via the current_user variable imported from the flask_login package.

The user variable is used to filter the Todo List in the database for todos created by the particular logged in user and it is also assigned to each todo created by the user.

You can see the authentication feature that was just added in action by running the application. Try to navigate to the \create-task and you'll get redirected to the login page.

Register as a new user and log in to the application. Once you are successfully logged in, you'll automatically get redirected to the create-task page. If you try to navigate to the /login or /register page while still logged in, you still get redirected to the create-task page.

You have successfully learnt how to add authentication to your application. With what you learnt in this series, you have all the ammunition required to build a great application now.

If you want to add styling to your application to make it look like this 👇,

head to Github, clone the repository, and make the necessary changes to your static and template files. Good luck!!

Congratulations!! We have come to the end of the journey. I hope you enjoyed the ride.

If you have any questions, feel free to drop them as a comment or send me a message on Linkedin or Twitter and I'll ensure I respond as quickly as I can. Ciao 👋

Building a Todo List Application with Flask

Faruq Abdulsalam — Tue, 23 Nov 2021 09:38:33 +0000

In this part of the series, you'll learn how to build a web application with the Flask framework. At the end of this part of the series, you'll have a working application with create, read, and delete functionalities.

Let's get started!!

Database Setup

The database that will be used here is sqlite, but you can choose any db of your choice.

You'll need to install the Flask-SQLAlchemy and Flask-Migrate extensions which will map all the data in your application to the sqlite db and also handle database migrations.

pip install flask-sqlalchemy

pip install flask-migrate

In the root directory, create a config.py and a .env file where all the configurations for the application will be stored.

touch config.py

touch .env

.env

First, set up the .env file by adding your secret key here. Remember that it is bad practice to hardcode your SECRET KEY in the main body of your application as this would make your application vulnerable to security breaches in production. That is why you need to always set it up as an environmental variable.

SECRET_KEY = put-your-own-secret-secret-key-here

Config.py

Then add your configurations:

import os
from dotenv import load_dotenv 

load_dotenv()
basedir = os.path.abspath(os.path.dirname(__file__))

class Configuration(object):
    SECRET_KEY = os.environ.get('SECRET_KEY')
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or \
        'sqlite:///' + os.path.join(basedir, 'todo.db')
    SQLALCHEMY_TRACK_MODIFICATIONS = False

Here os is imported to handle the paths and also retrieve data from the environment.

The load_dotenv function is imported from the installed dotenv package and then called. This loads the SECRET KEY variable stored in the .env file.

basedir = os.path.abspath(os.path.dirname(__file__))

The value assigned to the basedir variable is the path for the root directory. This is done to avoid hardcoding the path to the root directory which may change whenever you make changes to the structure of your directories.

Finally, the configuration settings are assigned to variables under the Configuration class.

i) the value of the SECRET KEY obtained when the load_dotenv function is called and assigned to the SECRET KEY variable.

ii) the database URL is obtained from the environment file and assigned to the SQLALCHEMY_DATABASE_URI variable. The or operator is used here so that if the database URL is not specified in the .env file, the variable DATABASE URL is set to the base directory. todo.db is the name of the database that'll be created in the root directory. You can choose to change the name of the db to whatever suits you.

iii) SQLALCHEMY_TRACK_MODIFICATIONS is set to false, this disables the feature which sends a signal every time the database changes.

The database and configuration setup is done. Now, you need to register it in your init.py script.

init.py

from flask import Flask
from config import Configuration
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

app = Flask(__name__)
app.config.from_object(Configuration)
db = SQLAlchemy(app)
migrate = Migrate(app, db)

from core import views, models

Import the Configuration class and configure the app variable with it. This assigns all the configuration settings to the application.

Next, import SQLAlchemy and Migrate from the packages installed earlier and configure them as done above.

models.py

You need to create a database module models.py in your core directory.

from core import db

class Todo(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(140))
    date = db.Column(db.Date())
    time = db.Column(db.Time())
    category= db.Column(db.String, db.ForeignKey('category.id'))

    def __repr__(self):
        return '<ToDo {}>'.format(self.title)

The db variable in the __init__.py file is imported here and used to set up the structure(columns) of the database.

The id field is declared as an integer type and the database will assign the primary key automatically.

The Todolist database model class will have title, date, and time fields as well so the title field is declared as a string type, date and time are declared as types date and time respectively.

Each todo created will also have a category, so you need to create a category field as type string. This will be connected to the Category database model that will be created later on.

The last line def __repr__(self): defines the format in which python will print the objects of this database model.

Blueprints

The application is about to grow massively, to prevent the project from becoming rough and confusing, and to ensure separation of concerns we'll be using Blueprints. Each part of the application will be made into modular applications which will all be registered in the __init__.py file in the core directory.

Let's start with the blueprint (mini-application) that will make it possible for the user to create todos. Create a new directory task in the core directory. Next, create the following files in the task directory: __init__.py, forms.py, models.py, and views.py.

Remember that this is going to be an application on its own so you need to create a templates folder in the task directory as well. Create a new folder task in it and within it a file named tasks.html.

task blueprint

Let's work on the init.py script.

init.py

from flask import Blueprint

task = Blueprint('task', __name__, template_folder='templates')

from . import views

The Blueprint class is imported from the flask package and the name of the current blueprint task is assigned to the constructor Blueprint(). The name is passed as an argument as well, as discussed earlier python automatically passes the name of the base module core here. Next, the folder in which the application will look for template files is assigned to the template_folder variable and also passed as an argument to the blueprint constructor.

Finally, the content of the views.py file will be imported into the script so that they can all be registered with the blueprint.

models.py

from .. import db

class Category(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(20))

    def __repr__(self):
        return '<Category {}>'.format(self.name)

The db variable is imported from the core directory and used to set up the Category database model class. This should be self-explanatory with the explanation done above when the Todo model class was created.

forms.py

To create the forms for the application you'll need to install Flask-WTF:

pip install flask-wtf

Then, you can create the various fields for the form that users will use to create todos.

from flask_wtf import FlaskForm
from wtforms import StringField, TimeField, DateField, SubmitField, SelectField
from wtforms.validators import DataRequired, Length, Email, EqualTo

class TaskForm(FlaskForm):
    title = StringField('Title', validators=[DataRequired()])
    category = SelectField('Category', coerce=int , validators=[DataRequired()])
    date = DateField('Date', format='%Y-%m-%d' , validators=[DataRequired()])
    time = TimeField('Time', format='%H:%M' , validators=[DataRequired()])
    submit = SubmitField('Add task')

A label is the first variable assigned to each form field declared, DataRequired is passed to the form validators as well to ensure that the fields are not left blank by the user.

The coerce keyword arg passed to the SelectField tells the application to use the int() function to coerce data for this particular field from the Task form.

views.py

from flask import render_template, redirect, url_for, request
from .models import Category
from ..models import Todo
from . import task
from .forms import TaskForm
from .. import db
from datetime import datetime

@task.route('/create-task', methods=['GET', 'POST'])
def tasks():
    check= None
    todo= Todo.query.all()
    date= datetime.now()
    now= date.strftime("%Y-%m-%d")

    form= TaskForm()
    form.category.choices =[(category.id, category.name) for category in Category.query.all()]

    return render_template('task/tasks.html', title='Create Tasks', form=form, todo=todo, DateNow=now, check=check)

First, the required functions from flask, model classes, db, form, and datetime class are imported into the views file.

The variable task is imported from the __init__.py blueprint script and is then extended as shown below with .route functions by mapping the URL and adding the HTTP methods which in this case are GET and POST.

@task.route('/create-task', methods=['GET', 'POST'])

This is used as a decorator for the tasks function defined below. In part 1 of the series app.route was used but since the task blueprint is being used here, you can simply use task.route since the blueprint will eventually be registered in the app.

The check variable initially assigned a value of None is simply used to pass an error message to the template. Next, the Todo table in the database is queried for all the todos in the database. This would later be changed when the authentication blueprint is set up. The present date is obtained and formatted using the strftime function.

Finally, the view uses render_template function to render the tasks.html file in the tasks directory located in the templates directory. The function also takes the title, form, DateNow, and check arguments that it will use to replace the placeholder variables that will be added to the task html file.

The choices for the select field are assigned the result of querying the Category table in the database. Let's test the application before adding the conditions that will handle the methods.

init.py

The task blueprint needs to be registered with the application so its content can also be recognized when the application is being run. Open the __init__.py script in the core directory and add the following lines before the last import line:

# blueprint for non-authentication parts of the app
from .task import task as task_blueprint
app.register_blueprint(task_blueprint)

The task variable to which the blueprint is assigned is imported from the task directory as task_blueprint and then registered with the application using the Flask inbuilt register_blueprint function.

Now you have to migrate the new database models to the database; you'll notice two new additions to your directory after doing this.

i) a new folder named migrations will be added to your root directory.

ii) a new database will also be created in your root directory bearing whatever name you specified in your config file. If you remember, the name of the db was specified as todo.db earlier on. If you made any change to yours, the database that will be created will bear the name you specified as well. Now let's see this in action. Run:

flask db init

You should see the new folder migrations added to your root directory. Next, run:

flask db migrate -m "Put any comment of your choice here"

Now you should see the created database todo.db in your root directory as well.

The last command to run is:

flask db upgrade

This will apply all the changes you made to the database model class to your database. Your directory should currently look like 👇.

The category table in the database is currently empty so let's go ahead and create the three categories that the user can choose when creating their todo list.

python shell

Open up the python shell in your terminal using:

python

Then, import the Category model from the task directory in the core directory and the db as well

from core.task.models import Category
from core import db

Create the three categories

ctgry1 = Category(name='Business')
ctgry2 = Category(name='Personal')
ctgry3 = Category(name='Other')

Now, the variables need to be added to the current database session using:

db.session.add(ctgry1)
db.session.add(ctgry2)
db.session.add(ctgry3)

Finally, the session is committed so that the changes are applied to the Category table in the database.

db.session.commit()

To confirm that the categories Business, Personal, and Other have all been added to the Category table in the database, run the commands below.

categories = Category.query.all()
for c in categories:
    print (c.name)

The categories should be printed out exactly like what is in the image below.

Before you can go ahead and run the application, you need to create the HTML code that will be rendered by the task view function.
First you need to create a base html file and then set up the task html file as an extension of the base file.

base.html

Create a new file named base.html inside the templates directory in the core directory.

<!doctype html>
<html>
    <head>

      {% if title %}
      <title>{{ title }} </title>
      {% else %}
      <title>Todo List</title>
      {% endif %}
    </head>
    <body>

        {% block content %} {% endblock content%}

    </body>
</html>

If you are new to jinja2 templates, the curly braces might look odd. The variable declared in the curly braces gets passed the value assigned to the variable when the render_template function is called in the view. For example, Create Tasks has already been assigned to the title variable so whenever the render_template function is executed, {{title}} in the tasks.html file gets replaced with Create Tasks. In jinja templates you can also make use of conditions such as if and for.

Every other html file in the application will be an extension of this base.html file and their contents will be filled into {% block content %} {% endblock content%}.

tasks.html

{% extends "base.html" %}

{% block content %}

<div class="task_content categories" >    
    <div class="">
        <div class="content">
            <div class="welcome">
                <button id="openbutton" class="openbtn" >&#9776;</button>
                <span class="welcome-text">Manage Your ToDo List</span> 
            </div>

            <form action="" method="post" novalidate>
                {{ form.hidden_tag() }}
                <div class="inputContainer Task">
                    {{ form.title.label }}<br>
                    {{ form.title(size=20) }}
                    {% for error in form.title.errors %}
                    <span style="color: red;">[{{ error }}]</span>
                    {% endfor %}
                </div>
                <div class="inputContainer choice ">
                    {{ form.category.label}}<br>
                    {{ form.category}}
                    {% for error in form.category.errors %}
                    <span style="color: red;">[{{ error }}]</span>
                    {% endfor %}
                </div>
                <div class="inputContainer  date ">
                    {{ form.date.label }}<br>
                    {{ form.date }}
                    {% for error in form.date.errors %}
                    <span style="color: red;">[{{ error }}]</span>
                    {% endfor %}
                </div>
                <div class="inputContainer  time">
                    {{ form.time.label }}<br>
                    {{ form.time }}
                    {% for error in form.time.errors %}
                    <span style="color: red;">[{{ error }}]</span>
                    {% endfor %}
                </div>
                <div class="buttons">   
                    {{ form.submit(class="taskAdd btn") }}
                </div> 
            </form>
            <!-- Task Delete Error alert -->
            {% if check %}
                <div class="alert alert-warning" role="alert">
                    <span class="closebtns" onclick="this.parentElement.style.display='none';">&times;</span>
                    {{check}}
                </div>
            {% endif %}
            <!-- End Task Delete error alert -->

            <form action="" method="post">
              {{ form.hidden_tag() }} <!-- csrf token for security -->

              <div class="tabs effect-1">
                 <!-- tab-content -->
                <div class="tab-content">
                  <section id="tab-item-1">
                      <ul class="taskList">        
                          {% for todo in todo %} 
                          <li class="currentTaskItem">
                              <input type="checkbox" class="taskCheckbox" name="checkedbox" id="{{ todo.id }}" value="{{ todo.id }}" >
                              <label for="{{ todo.id }}"><span class="complete-">{{ todo.title }}</span></label>
                              <span class="taskDone" >at</span>
                              <strong class="taskDone"><i class="fa fa-clock-o"></i> {{ todo.time }}</strong>
                              <span class="taskDone" >on</span>
                              <strong class="taskDatee taskDone"><i class="fa fa-calendar"></i> {{ todo.date }}</strong>
                              <span class="categorypage-{{ todo.category }}">{{ todo.category }}</span>
                              <button class="taskDelete " name="taskDelete" formnovalidate="" type="submit" ><i class="fa fa-trash-o icon"></i></button>
                          </li>     
                          {% endfor %}
                      </ul> <!--end All-Tasks-List -->
                  </section>
                </div><!-- end tab content -->
              </div><!-- end tab effect -->
            </form>
        </div><!-- end content -->

    </div><!-- container -->
</div>
{% endblock %}

The form.hidden_tag() gets the csrf token which protects the form against cross site request forgery(csrf) attacks.

In the first form in the HTML file, the labels set when creating the TaskForm e.g {{ form.title.label }} are used as the labels for the input elements. While the input elements are created using the fields created in the form e.g {{ form.title(size=20) }}.

The size=20 argument is an example of how to pass classes/attributes to the form field inputs. This sets the width of the input field to 20.

The if check line confirms if an error message exists and then renders the error alert elements if it does. Otherwise, no error message is displayed.

In the second form, you first need to confirm that a todo list exists from the database query made in the view. Then, the result is looped through to get the title, time, date, and category variables and displayed as li elements accordingly.

The action attributes in the forms are left blank because they'll both be sending form data to the page url.

Now let's see what has been built so far in the web browser. Run:

flask run

Your web browser should still be displaying Hello there, Ace. Navigate to http://127.0.0.1:5000/create-task and you'll see the page below.

Note that the title of the webpage was updated to what was specified in the render template function; title='Create Tasks' and the form was rendered as a normal form even though you didn't exactly create form inputs in the HTML file. Flask-WTF handles this for you.

Now, let's finish up the task view so that it can handle POST data from the front end. Add the following conditions to the task function.

    if request.method == "POST":
        if request.form.get('taskDelete') is not None:
            deleteTask = request.form.get('checkedbox')
            if deleteTask is not None:
                todo = Todo.query.filter_by(id=int(deleteTask)).one()
                db.session.delete(todo)
                db.session.commit()
                return redirect(url_for('task.tasks'))
            else:
                check = 'Please check-box of task to be deleted'

        elif form.validate_on_submit():
            selected= form.category.data
            category= Category.query.get(selected)
            todo = Todo(title=form.title.data, date=form.date.data, time= form.time.data, category= category.name)
            db.session.add(todo)
            db.session.commit()
            return redirect(url_for('task.tasks'))

All the logic here will only be run if the method is a POST request. Otherwise, the empty form will be rendered once again without any data. The if condition contains two further conditions to check whether the user wants to delete or create a todo.

Each todo will be rendered as a form with a delete button attached to it so if a post request is made the first condition checks if it was one of the delete forms that was submitted using the name attribute taskDelete of the delete form's submit button specified in the task template file.

If the condition passes, the next condition confirms that the checkbox was also checked before the Todo table in the database is queried by filtering with the id of the particular todo whose delete button was clicked. .one() at the end of the query, limits the number of rows returned from the database to one and that would be only the todo with the specified id. If the checkbox was not checked before the submit(Delete button) was pressed, an error message is displayed notifying the user that it needs to be checked before the todo can be deleted.

Then just like you did when the categories were created in the python shell, you also need to pass the todo object obtained from the database to the session and then commit it so that the changes will be applied to the database. After this is done, the page is made to refresh with the redirect function by passing the same view function tasks as an argument. task.tasks is used here since you are working in the task blueprint and this lets the application know the path to the task view.

However if the first condition evaluates to false, the second condition is executed and the form data is extracted after the data submitted by the user has been validated. The selected category comes back as an integer value(the id) not a string since the coerce argument was set to int() for the selectField in the forms.py file. The id value is then used to query the Category table in the database to get its matching Category in the db. Next, all the data passed from the form is used to generate the object passed to the todo variable, passed to the session, and finally committed to the database for storage. Thus, creating a new todo in the database. When this is completed, the page is made to refresh as well with the redirect function by passing the same view function tasks as an argument.

Your task function should look exactly like 👇

The create and delete functions have been created so you can put them to test now. Run your application:

flask run

Fill the task form and click on the Add Task button. Upon submission you'll notice that the web page reloads, the form is reset to default and your new task gets displayed.

The button circled in red in the picture above is the delete button, click on it to delete the created todo. You'll get the error message specified in the task view which is to notify the user that the checkbox needs to be checked. This helps to introduce a form of control for the delete button, making it impossible for the user to delete a created todo by mistake. Check the box of the todo and click on the delete button once again. Now you'll notice that the todo gets deleted.

Congratulations!! You have successfully created your first FLASK application with create, read, and delete features. This is the end of part 2 of the Flask series. Authentication will be added to the application in part 3. Cheers!!!

If you have any questions, feel free to drop them as a comment or send me a message on Linkedin or Twitter and I'll ensure I respond as quickly as I can. Ciao 👋

Getting started with Flask

Faruq Abdulsalam — Sat, 20 Nov 2021 08:26:08 +0000

Hello there, welcome to the Flask world. In this series, you are going to learn how to build a web application using the micro web python framework Flask. Let's get started!

The code for this series has been made available on Github. However, I strongly advise you to follow the tutorial and create the application with what you will learn here rather than cloning the repo straightaway. You can then choose to access the repo at the end.

The Github repo can be accessed via this link.

In this part of the series, you are going to learn how to set up your Flask project and display a simple message in your browser. Let's get started.

Setup

I’ll assume that you already have python installed on your machine. If you don't, you can download and set it up via this link. Please ensure you download the latest version of python. (Python 3.97)

Open the Command Line on Windows, Terminal on Mac, and Linux and navigate to the directory where you want to store the project and create a new directory

mkdir flask

Move into the new directory

cd flask

Create a Virtual environment.

For mac/unix users: python3 -m venv env
For windows users: py -m venv env

After creating the environment, activate it by running :

For mac/unix users: source env/bin/activate
For windows users: .\env\Scripts\activate

You can deactivate it by simply running the command below, but you don't have to deactivate it yet.

deactivate

Installing Flask

First you have to install Flask,

pip install flask

You are officially done with setting up your system for the flask project 🤝, now let us proceed to the project setup itself.

Setting up the project

Create a new directory inside the flask directory

mkdir core

Move into the new directory

cd core

Next create two new files __init__.py and views.py with the commands:

touch __init__.py

touch views.py

init.py

from flask import Flask

app = Flask(__name__)

from core import views

In the created script, the Flask class is imported from the installed flask package, and a __name__ variable is passed to it and they are finally assigned to an app variable.

The __name__ variable which is automatically set by python helps to get the name/location of the module in which the __init__.py script is called. In this case, __name__ is core because the script file __init__.py is located in the core directory and this tells Flask where to look for resources such as templates and static files. You will understand this better when the application starts becoming large and new packages are created to separate concerns.

Finally, the views.py module is imported from the project directory into the script. You must have noticed that the import is done at the bottom of the file, not at the top. The reason for this is to prevent the issue of circular imports. The routes module is being imported into the script but you will also need to import the app variable in the views.py module which might lead to an error due to cyclical dependencies.

views.py

from core import app

@app.route('/')
def index():
    return 'Hello Ace'

The app variable declared in the __init__.py script is imported here and used as a decorator. The line @app.route('/') is a python decorator made available by flask and this is used to modify the index function called below it and to assign the URL "/" to the function. Thus, the index function gets executed whenever a user navigates to the specified URL mapped to it.

base.py

To finish up, return to the root directory flask and create a base.py file

cd ..

touch base.py

and import the app variable into the script.

from core import app

running the application

To run the application, you need to export the script in the root directory base.py

export FLASK_APP=base.py

then run:

flask run

Navigate to the URL http://127.0.0.1:5000/ in your web browser and the page below should be displayed.

To run the flask application whenever you open up a new terminal, you have to always export the script in the root directory. The solution to this is to create an environment to store the assignment of the script to the FLASK_APP. To do this you need to install the python-dotenv package.

pip install python-dotenv

Next, create a .flaskenv file in the root directory and store the assignment of the script to the FLASK_APP in it:

touch .flaskenv

FLASK_APP=base.py

Note: Please dont forget the '.' infront of flaskenv. If you do, this process won't work.

Now, whenever you open a new terminal, you can just go ahead and run the application with:

flask run

Note: To run the application without getting any error.You need to always be in the root directory before running the command flask run

The project setup is done, this should be the current look of your directory.

Templates

Flask uses jinja2 template format by default.

index.html

Create a folder named templates in the core directory and create a file named index.html in it.

cd core

mkdir templates

cd templates

touch index.html

and put these basic lines of code in your HTML file.

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Test HTML</title>
    </head>
    <body>
        <h1>{{greet}}</h1>
    </body>
</html>

Here, a value will be assigned to the greet variable included in the h1 element whenever the index.html file is being rendered. This will be explained better below.

views.py

from flask import render_template
from core import app

@app.route('/')
def index():
    greeting="Hello there, Ace"
    return render_template('index.html', greet=greeting)

Next, some changes will be made to the views.py file. You have to import the render_template function from the flask package. The function renders the template file index.html and assigns the value of the greeting variable to the greet variable in the HTML file.

You can test this by running the application with

flask run

Then open your web browser and navigate to the same URL as before http://127.0.0.1:5000/. You should see your h1 element with the value of the variable greeting declared in views.py.

We have finally come to the end of the first part of the series. With the simple examples given above, I am sure you can easily set up a new flask application for your project and also pass data from the backend to template files.

In the next part of the series, we'll start creating our web application. Things will start getting complex but I'll make sure I break it down as much as I can. See you there!! Cheers!!!

If you have any questions, feel free to drop them as a comment or send me a message on Linkedin or Twitter and I'll ensure I respond as quickly as I can. Ciao 👋

DEV Community: Faruq Abdulsalam

How to Invoke a Lambda Function via API Gateway Locally Using Terraform and LocalStack (PDF Generator – Part 3)

Prerequisites

How to Build and Test a PDF Generator Lambda Using LocalStack on Your Local Machine (Part 2: Using Terraform)

Prerequisites

How to Build and Test a PDF Generator Lambda Using LocalStack on Your Local Machine

Prerequisites

FILES and CODE

SERVICES SETUP AND TESTING

How to Simulate AWS S3 on Your Local Machine with LocalStack

Prerequisites

LocalStack Setup

Local Environment Setup

Create an S3 bucket in the LocalStack container

Next Steps

Simplifying Local AWS Development with LocalStack

How to Integrate Next-Auth with Your Next.js Application

Prerequisites

Congratulations , you have successfully integrated your next js application using the app router with auth.js v5.

How to add login authentication to a Flask and React application.

Prerequisites

Flask Backend

Installing the flask extension.

base.py

token(login) API endpoint

Logout API endpoint

Refreshing tokens

React Frontend

Storage of token in the frontend

useToken.js

App.js

Login.js

Header.js

Profile.js

App.css

How to connect Flask to ReactJs

Prerequisite

Project directory

React frontend setup

Flask backend setup

Virtual environment

Installing Flask

base.py

Connecting the API endpoint(/profile) to the react frontend

Install the axios library:

package.json

app.js

Uploading media files to your Flask application

Prerequisite

Configurations

static/uploads directory

.env

config.py

init.py

views.py

index.html

Adding authentication to a Flask application

auth blueprint

auth blueprint

models.py

forms.py

views.py

login.html

register.html

init.py

models.py (base)

or

init.py

views.py

Building a Todo List Application with Flask

Database Setup

.env

Config.py

init.py

models.py

Blueprints

task blueprint

init.py

models.py

forms.py

Install the `axios` library: