Next.js Staging Deployment v1.0



This solution provides automated staging deployment for Next.js applications using GitLab CI/CD and Docker Swarm with Traefik.

🚀 Quick Install



Online Install (Recommended):
curl -sSL https://stage-tools.tyche.q2.cz/nextjs/v1.0/install.sh | bash


Download & Run:
curl -O https://stage-tools.tyche.q2.cz/nextjs/v1.0/install.sh

chmod +x install.sh

./install.sh


Web Interface:
Visit https://stage-tools.tyche.q2.cz for a full solution browser.

Features



  • 🚀 Optimized Docker builds with multi-stage building and caching

  • 🔄 Automated CI/CD with GitLab pipelines

  • 🌐 Traefik integration for automatic SSL and routing

  • đŸ“Ļ Redis support for caching and sessions

  • 🎛ī¸ Configurable via YAML files

  • 🛡ī¸ Production-ready with security best practices


    • Prerequisites



  • Next.js project with package.json

  • GitLab repository with CI/CD enabled

  • Docker Swarm cluster with Traefik

  • GitLab runners with Docker support


    • Installation



    🌐 Web Interface (Recommended)



    Visit the Stage Tools Web Interface to browse solutions and get installation commands:

    https://stage-tools.tyche.q2.cz

    The web interface provides:
  • 📖 Interactive documentation with syntax highlighting

  • 💾 Copy-paste installation commands for multiple methods

  • 🔍 Solution browser with status and features

  • 📋 Template previews and configuration examples


    • Manual Installation



    If you prefer command-line installation:

    Clone stage-tools repository

    
git clone git@gitlab.com:your-org/stage-tools.git /tmp/stage-tools
    

    

    Run installer from your Next.js project root

    
cd /path/to/your/nextjs/project
    
/tmp/stage-tools/nextjs/default/v1.0/install.sh
    

    

    Clean up

    
rm -rf /tmp/stage-tools


    1. Download the install script:
    wget https://gitlab.com/your-org/stage-tools/-/raw/main/nextjs/default/v1.0/install.sh
    
chmod +x install.sh


    2. Run the interactive setup:
    ./install.sh


    Configuration



    The script will ask for:

  • Project name - Used for service naming

  • Node.js version - For Docker base image

  • Domain suffix - Your deployment domain (e.g., yourdomain.com)

  • Service names - Names for Next.js, backend, and Redis services

  • GitLab runner tags - Tags for your build and deploy runners

  • Traefik settings - Network name and certificate resolver


    • Generated Files



    After installation, you'll have:

    your-project/
    
├── .gitlab-ci.yml                           # GitLab CI/CD pipeline
    
├── .dockerignore                            # Docker build optimization
    
└── .q2/
    
    ├── config/
    
    │   └── config.yaml                      # Service configuration
    
    └── staging/
    
        ├── Dockerfile.stage                 # Optimized Next.js Dockerfile
    
        └── generate-nextjs-compose.sh       # Dynamic compose generator


    Usage



    1. Configure Next.js for standalone output in next.config.js:
    /* @type {import('next').NextConfig} /
    
const nextConfig = {
    
  output: 'standalone',
    
  // ... other config
    
}
    

    
module.exports = nextConfig


    2. Push to staging branch (default: stage):
    git push origin stage


    3. Monitor deployment in GitLab CI/CD pipelines

    4. Access your application at:
    https://[service-name].[domain-suffix]


    Customization



    Environment Variables



    Add environment variables in .q2/config/config.yaml:

    domain_suffix: yourdomain.com
    
nextjs:
    
  name: myapp
    
  env:
    
    CUSTOM_VAR: value
    
backend:
    
  name: myapp-api
    
redis:
    
  name: redis
    
  port: 6379


    Build Scripts



    The installer detects common build script names:
  • build:test

  • build:prod

  • build:stage

  • build (default)


    • Ensure your package.json has the correct script.

    Docker Optimization



    The generated Dockerfile includes:
  • Multi-stage builds for smaller images

  • Build cache mounting

  • Layer optimization

  • Security hardening


    • Troubleshooting



    Common Issues



    1. "No package.json found"
    - Run the script from your Next.js project root

    2. "Build script not found"
    - Ensure your package.json has the specified build script
    - Update the script name in the installer

    3. Deployment fails
    - Check GitLab runner has Docker access
    - Verify runner tags match configuration
    - Check Traefik network exists

    4. SSL certificate issues
    - Verify your domain DNS points to the server
    - Check Traefik certificate resolver configuration

    Logs and Debugging



  • GitLab CI logs: Check pipeline output in GitLab

  • Container logs: Use docker service logs [service-name]

  • Traefik logs: Check routing and SSL generation


    • Advanced Configuration



    Custom Dockerfile



    To modify the Dockerfile generation, edit:
    .q2/staging/generate-nextjs-compose.sh


    Multiple Environments



    Copy and modify the solution for different environments:
    Create production variant

    
cp -r .q2/staging .q2/production
    

    Modify configurations as needed


    Migration from Existing Setup



    If migrating from manual Docker setup:

    1. Backup existing files
    2. Run the installer
    3. Compare and merge custom configurations
    4. Update GitLab CI/CD variables
    5. Test deployment

    Security Considerations



  • Never commit secrets to git

  • Use GitLab CI/CD variables for sensitive data

  • Keep base images updated

  • Review generated Dockerfile for your security requirements

  • Implement proper CORS and CSP headers in your Next.js app


    • Support



  • Check generated README files

  • Review GitLab CI/CD logs

  • Verify Docker Swarm and Traefik configuration

  • Test locally with docker build