Skip to content

Instantly share code, notes, and snippets.

@decagondev

decagondev/aws-deployment-guide.md

Last active August 13, 2025 15:29
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save decagondev/40d8b22daff5a1d4260b2f5ec3b93201 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save decagondev/40d8b22daff5a1d4260b2f5ec3b93201 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
aws-deployment-guide.md

AWS Deployment Guide

Assuming you have an AWS IAM console login with admin privileges (which gives you full access to create resources). We'll deploy your Next.js 14 app (with API routes as backend) using AWS Amplify for hosting the frontend and backend, and AWS RDS for a PostgreSQL database (replacing Supabase). AWS Amplify is beginner-friendly as it handles deployment, CI/CD, and scaling automatically.

Important Notes Before Starting:

  • This assumes your app is in a Git repository (e.g., GitHub). If not, push it to GitHub first.
  • We'll use the AWS Management Console (web interface) for all steps—no CLI needed.
  • Costs: AWS has a free tier, but RDS and Amplify may incur small charges (e.g., ~$0.025/hour for a basic RDS instance). Monitor via AWS Cost Explorer.
  • Security: Use environment variables for secrets (e.g., DB connection strings, API keys). Avoid hardcoding them.
  • Time Estimate: 1-2 hours for setup, plus deployment time.
  • If your app already has Supabase/Prisma setup, you'll need to update your Prisma schema and connection string to point to RDS.
  • For auth (NextAuth), payments (Stripe), and APIs (OpenAI/GitHub), add their secrets as environment variables in Amplify.
  • IAM Roles: AWS services like Amplify and RDS will automatically create necessary roles during setup. You don't need to manually create roles upfront, but we'll explain them as we go.

Prerequisites

  1. AWS Account Access: Log in to the AWS Management Console with your IAM admin credentials.
  2. App Preparation:
    • Ensure your Next.js app is ready: package.json includes all dependencies (e.g., Prisma, NextAuth).
    • In your prisma/schema.prisma, set the datasource to PostgreSQL (it should already be if using Supabase).
    • Test locally with npm run dev.
    • Commit and push to GitHub (public or private repo).
  3. Domain (Optional): If you have a custom domain, you can add it later in Amplify.

Step 1: Create an AWS RDS PostgreSQL Database

RDS is AWS's managed PostgreSQL service. We'll create a simple instance.

  1. Log in to the AWS Console.
  2. Search for "RDS" in the top search bar and select Amazon RDS.
  3. Click Create database.
  4. Under Database creation method, choose Standard create.
  5. Under Engine options:
    • Engine type: PostgreSQL.
    • Version: Select the latest (e.g., PostgreSQL 16.x).
  6. Under Templates, select Free tier (to keep costs low; suitable for dev/testing).
  7. Under Settings:
    • DB instance identifier: Enter a name like my-nextjs-db.
    • Master username: Enter admin (or your choice).
    • Master password: Create a strong password (note it down securely).
  8. Under DB instance class: Leave as default (db.t4g.micro for free tier).
  9. Under Storage: Leave defaults (20 GiB, general purpose SSD).
  10. Under Connectivity:
    • Compute resource: Don't connect to an EC2 compute resource.
    • Virtual private cloud (VPC): Select Default VPC.
    • Subnet group: Select default.
    • Public access: Yes (for easy access from your app; in production, set to No and use VPC peering).
    • VPC security group: Choose Create new VPC security group and name it nextjs-db-sg.
    • Availability Zone: No preference.
    • Database port: 5432 (default).
  11. Under Database authentication: Password authentication.
  12. Under Additional configuration:
    • Initial database name: Enter mydatabase (or your app's DB name).
    • Leave other defaults.
  13. Click Create database. It may take 5-10 minutes to launch.
  14. Once ready, go to RDS > Databases > Your DB > Connectivity & security tab.
    • Note the Endpoint (e.g., my-nextjs-db.xxxxxxx.rds.amazonaws.com) and Port (5432).
    • Connection String Example: postgresql://admin:YOUR_PASSWORD@ENDPOINT:5432/mydatabase.
  15. Security Note: Edit the security group (under VPC > Security Groups) to allow inbound traffic on port 5432 from your IP (for local testing) or Amplify's IP range (add later if needed). Rule: Inbound > Type: PostgreSQL > Source: My IP.

IAM Role Explanation: RDS doesn't require a custom IAM role here. AWS handles instance roles internally.

Step 2: Update Your App to Use AWS RDS

Now, configure your Next.js app to connect to RDS instead of Supabase.

  1. In your local code:
    • Install Prisma if not already: npm install prisma @prisma/client.
    • Run npx prisma init if no schema exists.
  2. Update prisma/schema.prisma: 
    datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
  3. In your .env file (or .env.local for dev):
    • Add DATABASE_URL="postgresql://admin:YOUR_PASSWORD@RDS_ENDPOINT:5432/mydatabase?schema=public".
  4. If using NextAuth with PostgreSQL adapter:
    • Install: npm install @auth/prisma-adapter.
    • Update your NextAuth config to use the Prisma adapter with the DB.
  5. For migrations: Run npx prisma migrate dev --name init locally to create tables.
  6. Test connection locally: Run your app and query the DB (e.g., via Prisma client).
  7. Add other env vars:
    • OpenAI: OPENAI_API_KEY=your_key.
    • GitHub: GITHUB_TOKEN=your_token.
    • Stripe: STRIPE_SECRET_KEY=your_key (and webhook secrets).
    • NextAuth: NEXTAUTH_SECRET=your_secret, NEXTAUTH_URL=https://your-domain.com.
  8. Commit and push changes to GitHub.

Note: In production, never commit .env. Use Amplify's environment variables (Step 4).

Step 3: Set Up AWS Amplify for Deployment

Amplify hosts your Next.js app (frontend + API routes) with automatic builds and SSR support.

  1. In AWS Console, search for "Amplify" and select AWS Amplify.
  2. Click Get started under Host web app.
  3. Under Deploy from a Git provider, select GitHub (authorize Amplify to access your repo if prompted).
  4. Select your repository and branch (e.g., main).
  5. Under App name, enter something like my-nextjs-app.
  6. Under Environment, select Production or create a new one.
  7. Amplify will detect your framework: Confirm it's Next.js - SSR.
  8. Under Build settings:
    • Amplify auto-generates a build spec. For Next.js 14 with App Router, it should include:
      • Build command: npx next build.
      • Output directory: .next.
    • If needed, edit to add Prisma migrations: Add a preBuild command like npx prisma migrate deploy.
  9. Click Next.
  10. Review and click Save and deploy. Amplify will clone your repo, build, and deploy.
  11. Deployment takes 5-10 minutes. Once done, note the URL (e.g., https://main.xxxxx.amplifyapp.com).

IAM Role Explanation: Amplify creates a service role (e.g., amplify-xxxxx-service-role) with permissions for S3, CloudFront, etc. You can view it in IAM > Roles.

Step 4: Add Environment Variables in Amplify

Connect your app to RDS and add secrets.

  1. In Amplify Console, go to your app > App settings > Environment variables.
  2. Click Manage variables.
  3. Add:
    • DATABASE_URL: postgresql://admin:YOUR_PASSWORD@RDS_ENDPOINT:5432/mydatabase?schema=public.
    • Other vars: OPENAI_API_KEY, GITHUB_TOKEN, STRIPE_SECRET_KEY, NEXTAUTH_SECRET, etc.
  4. Save and redeploy (Amplify > Hosting > Redeploy).

Security Tip: For production, rotate passwords and use AWS Secrets Manager (advanced: integrate via IAM roles).

Step 5: Configure Database Connectivity from Amplify

Ensure Amplify can access RDS.

  1. If connection fails (e.g., timeout), update RDS security group:
    • Go to VPC > Security Groups > Your DB SG.
    • Add inbound rule: Type: PostgreSQL (5432), Source: 0.0.0.0/0 (temporary for testing; restrict to Amplify's IPs in prod).
  2. Test: Trigger a DB query via your deployed app's API.

Step 6: Set Up Continuous Deployment

Amplify handles CI/CD automatically.

  1. Any push to your Git branch triggers a rebuild/deploy.
  2. Monitor builds in Amplify > Hosting > Builds.

Step 7: Additional Configurations

  • Custom Domain: Amplify > Domain management > Add domain.
  • Stripe Webhooks: In Stripe dashboard, add your Amplify URL + /api/stripe-webhook.
  • NextAuth: Ensure NEXTAUTH_URL is your deployed URL.
  • Monitoring: Use AWS CloudWatch for logs (Amplify integrates automatically).
  • Scaling: Amplify auto-scales; RDS can be upgraded via Modify DB.
  • Cleanup: To avoid costs, delete RDS instance and Amplify app when done.

Troubleshooting

  • Build fails? Check logs in Amplify > Builds.
  • DB connection error? Verify security group, endpoint, and env vars.
  • Need help? Use AWS Support (free basic) or forums.

At this pointy our app is now deployed on AWS with a PostgreSQL DB. If issues arise, provide error messages for further guidance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment