Deployment and CI/CD

This document outlines the process for deploying the TRMNL Salah Prayer Times Plugin backend to AWS using the Serverless Framework and details the continuous integration and deployment (CI/CD) pipeline implemented with GitHub Actions.

AWS Deployment

The project leverages the Serverless Framework↗ to define, build, and deploy the application's backend infrastructure (AWS Lambda functions, API Gateway, etc.) as code. This approach simplifies the management of serverless resources and ensures consistency across environments.

Deployment Process

To deploy the backend to AWS:

1. Prerequisites:

   • Ensure you have an AWS account configured with the Serverless Framework CLI. This typically involves setting up AWS credentials locally that the Serverless Framework can use.
   • You must have Node.js and Yarn installed as per the [Getting Started & Local Development] guide.
   • The required environment variables (TRMNL_CLIENT_ID, TRMNL_CLIENT_SECRET, SUPABASE_URL, SUPABASE_SERVICE_KEY) must be set in your deployment environment (e.g., via a .env file or environment variables for the CI/CD pipeline).

2. Install Dependencies: If you haven't already, install the project's dependencies:

3. Deploy: Execute the Serverless deploy command from the project root. This command will package your TypeScript code, create or update AWS resources (Lambda functions, API Gateway endpoints, etc.), and deploy them to your configured AWS region (eu-west-2 as per serverless.yml).

   Upon successful deployment, the Serverless Framework will output the API Gateway URL for your endpoints (e.g., https://your-api-gateway-url/install, https://your-api-gateway-url/prayer-times). This URL is crucial for configuring the plugin in the TRMNL dashboard.

CI/CD Pipeline with GitHub Actions

The project uses GitHub Actions to automate the continuous integration and deployment workflow, ensuring code quality and efficient delivery. The pipeline is defined in the .github/workflows/build-and-deploy.yml file.

Workflow Triggers

The CI/CD pipeline is triggered in the following scenarios:

• Continuous Integration (CI):

  • On every push to any branch.
  • On every pull_request targeting the main branch. This ensures that all proposed changes are automatically validated before being merged.

• Continuous Deployment (CD):

  • After a successful CI run on a push to the main branch. This enables automatic deployment of tested and verified code to the production environment.

Stages of the Pipeline

The GitHub Actions workflow comprises two main stages:

1. Continuous Integration (CI)

This stage focuses on validating the codebase and runs for all pushes and pull requests.

• Checkout Code: Fetches the repository's code.
• Setup Node.js: Configures the Node.js environment (version 20.x).
• Install Dependencies: Installs all project dependencies using yarn.
• Run Linter: Executes ESLint (yarn lint) to enforce coding standards and identify potential issues.
• Type Checking: Performs TypeScript type checking (yarn check-types) to catch type-related errors.
• Run Tests: Executes unit and integration tests using Jest (yarn test) to ensure functionality and prevent regressions.

If any of these CI steps fail, the workflow stops, and the changes are flagged, preventing them from proceeding to deployment.

2. Continuous Deployment (CD)

This stage is responsible for deploying the application to AWS and runs only when the CI stage is successful and the changes are pushed to the main branch.

• Checkout Code: Fetches the repository's code.
• Setup Node.js: Configures the Node.js environment.
• Install Dependencies: Installs project dependencies.
• Serverless Deployment: Uses the Serverless Framework to deploy the application to AWS.
  • This step invokes yarn serverless:deploy.
  • The deployment targets the production stage (configured implicitly via serverless.yml and environment variables).
  • AWS credentials are provided via GitHub Secrets.
  • TRMNL and Supabase credentials are also passed as environment variables to the deployment process for runtime configuration.

GitHub Repository Secrets for CI/CD

To enable the GitHub Actions pipeline to deploy to AWS and interact with TRMNL and Supabase, the following secrets must be configured in your GitHub repository's settings:

• AWS_ACCESS_KEY_ID: Your AWS Access Key ID, required for the GitHub Actions runner to authenticate with your AWS account and deploy resources.
• AWS_SECRET_ACCESS_KEY: Your AWS Secret Access Key, providing programmatic access to your AWS account.
• TRMNL_CLIENT_ID: The Client ID issued by TRMNL when you registered your plugin. This is used by the backend for OAuth flows.
• TRMNL_CLIENT_SECRET: The Client Secret associated with your TRMNL plugin. Also used for secure OAuth communication.
• SUPABASE_URL: The URL of your Supabase project API, necessary for the backend to connect to your Supabase database.
• SUPABASE_SERVICE_KEY: The Supabase Service Role Key, which grants the backend appropriate permissions to interact with your database tables (e.g., user_settings).

These secrets ensure that sensitive credentials are not hardcoded into the repository but are securely managed and injected into the CI/CD pipeline at runtime.