Skip to content

getting-started.md

Latest commit

 

History

History
244 lines (171 loc) · 5.96 KB

getting-started.md

File metadata and controls

244 lines (171 loc) · 5.96 KB

Getting Started with Next.js DevOps Toolkit

This guide will help you get started with the Next.js DevOps Toolkit and deploy your Next.js application using the provided configurations and tools.

Prerequisites

Before you begin, ensure you have the following installed:

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/next-devops-toolkit.git
cd next-devops-toolkit

2. Explore the Example Application

The toolkit includes an example Next.js application in the example-app directory:

cd example-app
npm install
npm run dev

Visit http://localhost:3000 to see the example application running.

3. Docker Development Environment

To run the application in a Docker development environment:

cd docker
docker-compose -f docker-compose.development.yml up

This will start the application with hot reloading enabled.

4. Production Docker Build

To build and run a production Docker image:

cd docker
docker-compose -f docker-compose.production.yml up

Deployment Options

The toolkit provides several deployment options:

1. Kubernetes Deployment

To deploy to Kubernetes:

# Apply the development configuration
kubectl apply -k kubernetes/overlays/dev

# Or apply the production configuration
kubectl apply -k kubernetes/overlays/prod

2. Cloud Platform Deployment

Vercel

  1. Install the Vercel CLI:

    npm install -g vercel

  2. Deploy to Vercel:

    cd example-app
vercel

Netlify

  1. Install the Netlify CLI:

    npm install -g netlify-cli

  2. Deploy to Netlify:

    cd example-app
netlify deploy

AWS Amplify

  1. Install the AWS Amplify CLI:

    npm install -g @aws-amplify/cli

  2. Configure Amplify:

    amplify configure

  3. Initialize Amplify in your project:

    cd example-app
amplify init

  4. Deploy to Amplify:

    amplify publish

3. Infrastructure as Code with Terraform

To provision infrastructure using Terraform:

# Initialize Terraform
cd terraform/aws/eks
terraform init

# Plan the deployment
terraform plan -out=tfplan

# Apply the plan
terraform apply tfplan

Customizing for Your Project

1. Update Docker Configurations

Modify the Docker configurations in the docker directory to match your application's requirements:

  • Update the base image if needed
  • Adjust environment variables
  • Configure volume mounts

2. Customize Kubernetes Manifests

Adapt the Kubernetes manifests in the kubernetes directory:

  • Update resource limits and requests
  • Configure environment-specific settings
  • Adjust health check paths

3. Configure CI/CD Pipelines

Set up CI/CD pipelines using the GitHub Actions workflows in the .github/workflows directory:

  • Update repository secrets
  • Configure deployment targets
  • Adjust build and test commands

4. Set Up Monitoring

Configure monitoring using the provided configurations in the monitoring directory:

  • Deploy Prometheus and Grafana
  • Import the Next.js dashboard
  • Set up alerts

Directory Structure Overview

next-devops-toolkit/
├── docker/ - Docker configurations
├── kubernetes/ - Kubernetes manifests
├── terraform/ - Infrastructure as Code
├── .github/workflows/ - CI/CD pipelines
├── monitoring/ - Monitoring configurations
├── cloud-platforms/ - Cloud platform configurations
├── example-app/ - Example Next.js application
└── docs/ - Documentation

Common Workflows

Development Workflow

  1. Develop locally using npm run dev or Docker development environment
  2. Commit changes to a feature branch
  3. Create a pull request
  4. CI pipeline runs tests and builds
  5. Review and merge the pull request
  6. CD pipeline deploys to the appropriate environment

Production Deployment Workflow

  1. Merge changes to the main branch
  2. CI pipeline runs tests and builds
  3. CD pipeline deploys to staging environment
  4. Verify changes in staging
  5. Promote to production (manual approval or automatic)
  6. CD pipeline deploys to production environment
  7. Monitor application performance and logs

Troubleshooting

Docker Issues

  • Container fails to start: Check logs with docker logs <container_id>
  • Volume mounting issues: Ensure paths are correct in docker-compose.yml
  • Network issues: Check if ports are correctly mapped

Kubernetes Issues

  • Pods not starting: Check pod status with kubectl describe pod <pod_name>
  • Service not accessible: Verify service and ingress configurations
  • Resource constraints: Check if pods are hitting resource limits

CI/CD Issues

  • Build failures: Check GitHub Actions logs for errors
  • Deployment failures: Verify secrets and environment variables
  • Permission issues: Ensure service accounts have necessary permissions

Next Steps

Getting Help

If you encounter issues or have questions:

  • Check the documentation in the docs directory
  • Open an issue on GitHub
  • Contribute improvements via pull requests