rekliner/next-pm2-deploy

A template for deploying next sites with zero downtime to a linux server running pm2. It was written to allow Next.js apps to be conveniently run on AWS EC2 servers but would work with any host.

This is not a Nextjs app in itself, just a set of files to be added to your existing Nextjs app.

Features

• Follows the deployment methods used by envoyer.io
• Zero downtime: It only enables the new commit once the installation and build is successful. Then a symbolic link is "instantly" swapped to use the newest code.
• Responds to yoursite.com/api/deploy endpoint
• Rate limited to prevent endpoint abuse - using code from Vercel
• Checks for existing deployment operation to prevent running 2 concurrent deployments
• Optional deploy key header for basic security from gitlab or github
• Cancels deployment if it's the same commit as is currently live
• Cleans up older or failed deployment files to keep disk space consistant

Setup

• Install PM2 on the server. Command for Ubuntu/Debian is sudo apt install pm2
• Create a directory on the webserver for your project.
• Add a subdirectory releases and if persistant storage is desired storage
• Install reverse proxy like NGINX if you don't want traffic directly to your app. There are a million tutorials. The webroot should point to the current symbolic link in your project folder. (It is created at first deployment)
• Only the .env file needs to be edited. Necessary variables are in the .env.example in this repo.
• Multiple .env files supported. One or more can be present. The override heirachy is .env.local -> .env.staging -> .env.production -> .env
• Upload your .env file to the server in the main project directory
• Add the files in this template to your existing Next app repo (except this reamde, the license, and .env.example)
• Clone your next app into the releases directory: ex.git clone git@github.com:rekliner/next-pm2-deploy.git
• Enter the newly cloned directory and make the deploy script executable: sudo chmod -x deploy.sh
• Run the deploy script in the newly cloned folder: . deploy.sh or bash deploy.sh
• Save your PM2 setup to be persistant over server reboots: pm2 startup && pm2 save

What will happen when deployed

• A log file will be started in the current directory last_deploy.log
• A new directory will be created with the current timestamp in the releases directory
• Environment files and persistant storage will be linked from the main project folder
• NPM requirements will be installed
• A production build will be created using npx next build
• The current symbolic link will be recreated to point to this new build.
• The previous PM2 process will be deleted and a new one begun using npx next start with the new files

To deploy

• A visit to yoursite.com/api/deploy will trigger deployment. By default more than one visit a minute is ignored.
• In Github (link to docs) or Gitlab (link to docs) a Webhook can be set up for a branch under the repo Settings. Deployment will be triggered by an automatic request to yoursite.com/api/deploy whenever code is checked in to that branch.
• A deployment key or secret can be added to help secure your endpoint. (look for tutorials on the header this adds to the request)
• Running the deploy.sh script manually from one of the release directories will also work if you don't want to use the API/webhook method.