Step‑by‑Step Guide to Implementing Canary (Gray) Deployment with Nginx and Jenkins

Gray (canary) deployment is a technique where a new feature is first released to a small group of users to verify its correctness before rolling out to the whole audience. This article demonstrates how to set up a complete canary deployment pipeline from scratch using Nginx and Jenkins.

1. Server preparation – Two servers (or two ports on a single server) are required so that each can host a different version of the application. If you only have one machine, you can simulate the second server by using a different port.

2. Tool installation

Install Git: yum install git Install Nginx: sudo yum install nginx Verify the installation with nginx -t and start Nginx using nginx or nginx -s reload. After starting, accessing the server’s public IP should display the default Nginx page.

Install Jenkins (example for CentOS):

// download and install
wget http://pkg.jenkins-ci.org/redhat-stable/jenkins-2.204.5-1.1.noarch.rpm
rpm -ivh jenkins-2.204.5-1.1.noarch.rpm
// modify port if needed
vi /etc/sysconfig/jenkins
// start/stop/restart
service jenkins start
// initial admin password location
/var/lib/jenkins/secrets/initialAdminPassword

After completing the installation, create an admin account and log in to the Jenkins UI.

3. Code preparation

Two different builds of an Angular project are created to represent the old and new versions. Install Angular CLI, generate a project, and change the index.html title to distinguish the builds (e.g., A-CanaryDemo and B-CanaryDemo).

// install Angular CLI
npm install -g @angular/cli
// create project
ng new canaryDemo
cd canaryDemo
// serve locally to verify
ng serve
// build production packages
ng build --prod

Upload the two build folders to both servers (e.g., /var/canaryDemo).

4. Nginx configuration for canary routing

Copy the build to the server and edit /etc/nginx/nginx.conf to add a map that reads a canary cookie. If the cookie value is devui, traffic is sent to the canary upstream; otherwise it goes to the default upstream.

# Canary Deployment
map $COOKIE_canary $group {
  ~*devui$ server_canary;
  default server_default;
}

upstream server_canary {
  server 11.11.11.11:8000 weight=1 max_fails=1 fail_timeout=30s;
  server 22.22.22.22 weight=1 max_fails=1 fail_timeout=30s;
}

upstream server_default {
  server 11.11.11.11:8000 weight=2 max_fails=1 fail_timeout=30s;
  server 22.22.22.22 weight=2 max_fails=1 fail_timeout=30s;
}

server {
  listen 8000;
  root /var/canaryDemo;
  location / { root /var/canaryDemo; index index.html; }
}

server {
  listen 80 default_server;
  root /var/canaryDemo;
  location / { proxy_pass http://$group; }
}

Reload Nginx with nginx -s reload to apply the changes.

5. Defining the gray‑release workflow

The process consists of six steps: deploy new code to side A, route a small portion of traffic to A, manually verify, shift most traffic to A, verify side B, and finally balance traffic between A and B. Three Jenkins freestyle jobs are created to automate these steps: Canary_A, Canary_AB, and Canary_B.

6. Jenkins job configuration

Each job pulls the latest production package from a Git repository, copies it to /var/canaryDemo, and modifies the Nginx configuration using sed to comment/uncomment the appropriate upstream servers. Example shell for Canary_A:

git pull
rm -rf /var/canaryDemo
scp -r dist /var/canaryDemo
sed -i 's/server 22.22.22.22 weight=1/# server 22.22.22.22 weight=1/' /etc/nginx/nginx.conf
sed -i 's/server 11.11.11.11:8000 weight=2/# server 11.11.11.10 weight=2/' /etc/nginx/nginx.conf
nginx -s reload

Similar scripts are used for the other two jobs, adjusting the comments to direct traffic to the desired side.

After configuring the jobs, running them sequentially performs a full canary deployment: first testing on side A, then switching the canary to side B, and finally balancing traffic across both servers.

Conclusion

The article shows how to build a minimal gray‑release environment from zero, covering server setup, code packaging, Nginx traffic routing, and Jenkins automation. While the demo is simple, real‑world DevOps pipelines would also integrate build compilation, code quality checks, security scanning, and automated tests.