Nomad Deployment Examples

This document provides practical examples of using the pfy nomad commands for various deployment scenarios.

Table of Contents

• Basic Examples
• Version Management Integration
• Multi-Service Deployments
• Environment-Specific Deployments
• CI/CD Pipeline Examples

---

Basic Examples

Deploy with Explicit Tag

# Deploy manager service with version 1.2.3
pfy nomad deploy -f manager/nomad/manager.nomad --tag v1.2.3

Output:

Current image: ghcr.io/productifyfw/manager:latest
Updated Nomad HCL file: manager/nomad/manager.nomad
New image: ghcr.io/productifyfw/manager:v1.2.3
✓ Job file is valid
Running 'nomad job run manager/nomad/manager.nomad'...

✓ Job deployed successfully

Deploy with Image and Tag

# Deploy with both image name and tag
pfy nomad deploy \
  -f optimizer/nomad/optimizer.nomad \
  --image ghcr.io/productifyfw/optimizer \
  --tag v2.0.0

Update Image Only (No Deployment)

# Update the HCL file without deploying
pfy nomad update-image -f proxy/nomad/proxy.nomad --tag v1.5.0

Output:

Current: caddy:2.7-alpine
Updated: caddy:v1.5.0
File updated: proxy/nomad/proxy.nomad

---

Version Management Integration

Bump and Deploy

# Bump version in project.yaml
pfy version bump --part minor

# Deploy using the bumped version
pfy nomad deploy -f manager/nomad/manager.nomad --use-project-version

Output:

Version updated: 1.2.3 → 1.3.0
Configuration saved to project.yaml

Current image: ghcr.io/productifyfw/manager:v1.2.3
Updated Nomad HCL file: manager/nomad/manager.nomad
New image: ghcr.io/productifyfw/manager:v1.3.0
✓ Job file is valid
Running 'nomad job run manager/nomad/manager.nomad'...

✓ Job deployed successfully

Set Specific Version and Deploy

# Set version to 2.0.0
pfy version set --version 2.0.0

# Deploy all services with the new version
for service in manager optimizer proxy; do
  pfy nomad deploy -f $service/nomad/$service.nomad --use-project-version
done

---

Multi-Service Deployments

Deploy Full Stack

Create a deployment script:

#!/bin/bash
# deploy-stack.sh

set -e

VERSION=${1:-$(pfy version show)}

echo "Deploying ProductifyFW stack version $VERSION"

# Update version in project.yaml if provided
if [ -n "$1" ]; then
  pfy version set --version $VERSION
fi

# Deploy database first
echo "Deploying database..."
pfy nomad deploy -f database/nomad/postgres.nomad

# Deploy backend services
echo "Deploying manager..."
pfy nomad deploy -f manager/nomad/manager.nomad --use-project-version

echo "Deploying optimizer..."
pfy nomad deploy -f optimizer/nomad/optimizer.nomad --use-project-version

# Deploy proxy last
echo "Deploying proxy..."
pfy nomad deploy -f proxy/nomad/proxy.nomad --use-project-version

echo "✓ Full stack deployed successfully"

Usage:

# Deploy with current version
./deploy-stack.sh

# Deploy with specific version
./deploy-stack.sh 1.4.0

Staged Deployment with Validation

#!/bin/bash
# deploy-with-validation.sh

SERVICES=("manager" "optimizer" "proxy")

for service in "${SERVICES[@]}"; do
  echo "Validating $service..."
  pfy nomad validate -f $service/nomad/$service.nomad

  echo "Planning $service..."
  pfy nomad deploy -f $service/nomad/$service.nomad --use-project-version --plan-only

  read -p "Deploy $service? (y/n) " -n 1 -r
  echo
  if [[ $REPLY =~ ^[Yy]$ ]]; then
    pfy nomad deploy -f $service/nomad/$service.nomad --use-project-version
  fi
done

---

Environment-Specific Deployments

Development Environment

# Deploy to dev with latest build
pfy nomad deploy -f nomad/dev/manager.nomad --tag dev-latest

# Or use branch name
BRANCH=$(git rev-parse --abbrev-ref HEAD)
pfy nomad deploy -f nomad/dev/manager.nomad --tag dev-$BRANCH

Staging Environment

# Deploy to staging with specific version
pfy nomad deploy -f nomad/staging/manager.nomad --tag v1.3.0

# Or use project version
pfy nomad deploy -f nomad/staging/manager.nomad --use-project-version

Production Environment

# Always plan first in production
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.3.0 --plan-only

# Review output carefully, then deploy
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.3.0

Environment Deployment Script

#!/bin/bash
# deploy-env.sh <environment> <version>

ENV=$1
VERSION=$2

if [ -z "$ENV" ] || [ -z "$VERSION" ]; then
  echo "Usage: $0 <dev|staging|prod> <version>"
  exit 1
fi

NOMAD_FILE="nomad/$ENV/manager.nomad"

if [ ! -f "$NOMAD_FILE" ]; then
  echo "Error: $NOMAD_FILE not found"
  exit 1
fi

if [ "$ENV" = "prod" ]; then
  echo "Planning production deployment..."
  pfy nomad deploy -f $NOMAD_FILE --tag $VERSION --plan-only

  read -p "Proceed with production deployment? (yes/no) " CONFIRM
  if [ "$CONFIRM" != "yes" ]; then
    echo "Deployment cancelled"
    exit 0
  fi
fi

echo "Deploying to $ENV..."
pfy nomad deploy -f $NOMAD_FILE --tag $VERSION

echo "✓ Deployment to $ENV complete"

---

CI/CD Pipeline Examples

GitHub Actions Workflow

name: Deploy to Nomad

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:
    inputs:
      environment:
        description: "Deployment environment"
        required: true
        default: "staging"
        type: choice
        options:
          - dev
          - staging
          - prod

env:
  NOMAD_ADDR: ${{ secrets.NOMAD_ADDR }}
  NOMAD_TOKEN: ${{ secrets.NOMAD_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install pfy CLI
        run: |
          curl -LO https://github.com/ProductifyFW/cli/releases/latest/download/pfy-linux-amd64
          chmod +x pfy-linux-amd64
          sudo mv pfy-linux-amd64 /usr/local/bin/pfy

      - name: Extract version
        id: version
        run: |
          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/v}
          else
            VERSION=$(pfy version show)
          fi
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Deploy to staging
        if: github.event.inputs.environment == 'staging' || github.ref_type == 'tag'
        run: |
          pfy nomad deploy \
            -f nomad/staging/manager.nomad \
            --tag v${{ steps.version.outputs.version }}

      - name: Deploy to production
        if: github.event.inputs.environment == 'prod'
        run: |
          # Plan first
          pfy nomad deploy \
            -f nomad/prod/manager.nomad \
            --tag v${{ steps.version.outputs.version }} \
            --plan-only

          # Deploy
          pfy nomad deploy \
            -f nomad/prod/manager.nomad \
            --tag v${{ steps.version.outputs.version }}

GitLab CI/CD Pipeline

stages:
  - build
  - deploy:dev
  - deploy:staging
  - deploy:prod

variables:
  NOMAD_ADDR: $NOMAD_SERVER_URL

before_script:
  - curl -LO https://github.com/ProductifyFW/cli/releases/latest/download/pfy-linux-amd64
  - chmod +x pfy-linux-amd64
  - mv pfy-linux-amd64 /usr/local/bin/pfy

# Deploy to development on every commit
deploy:dev:
  stage: deploy:dev
  script:
    - VERSION=$(git rev-parse --short HEAD)
    - pfy nomad deploy -f nomad/dev/manager.nomad --tag dev-$VERSION
  environment:
    name: development
  only:
    - main

# Deploy to staging on tags
deploy:staging:
  stage: deploy:staging
  script:
    - VERSION=${CI_COMMIT_TAG#v}
    - pfy nomad deploy -f nomad/staging/manager.nomad --tag v$VERSION
  environment:
    name: staging
  only:
    - tags

# Deploy to production manually
deploy:prod:
  stage: deploy:prod
  script:
    - VERSION=${CI_COMMIT_TAG#v}
    - pfy nomad deploy -f nomad/prod/manager.nomad --tag v$VERSION --plan-only
    - pfy nomad deploy -f nomad/prod/manager.nomad --tag v$VERSION
  environment:
    name: production
  only:
    - tags
  when: manual

---

Rollback Scenarios

Quick Rollback

# Rollback to previous version
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.2.3

Rollback with Git

# Find previous version
git log --oneline project.yaml | head -5

# Checkout previous version
git show HEAD~1:project.yaml | grep version

# Rollback
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.2.3

Automated Rollback Script

#!/bin/bash
# rollback.sh <environment> <previous-version>

ENV=$1
PREV_VERSION=$2

if [ -z "$ENV" ] || [ -z "$PREV_VERSION" ]; then
  echo "Usage: $0 <environment> <version>"
  exit 1
fi

echo "Rolling back $ENV to $PREV_VERSION"

# Plan the rollback
pfy nomad deploy -f nomad/$ENV/manager.nomad --tag $PREV_VERSION --plan-only

read -p "Proceed with rollback? (yes/no) " CONFIRM
if [ "$CONFIRM" != "yes" ]; then
  echo "Rollback cancelled"
  exit 0
fi

# Execute rollback
pfy nomad deploy -f nomad/$ENV/manager.nomad --tag $PREV_VERSION

echo "✓ Rollback complete"

---

See Also

• Nomad Commands Reference
• Nomad Deployment Guide
• Version Management
• CI Commands