DEV Community

Cover image for Zero-Build Production Deployments: Shipping Next.js Apps via Docker TAR Artifacts
JAKER HOSSAIN
JAKER HOSSAIN

Posted on

Zero-Build Production Deployments: Shipping Next.js Apps via Docker TAR Artifacts

#docker #devops #nextjs #ai

Introduction
Building Next.js or heavy frontend images directly on a budget VPS often leads to CPU spikes, out-of-memory crashes, and slow deployments.

The solution? Build locally (or in CI), export as a .tar artifact, and ship pre-baked images.

This guide covers a zero-build VPS deployment pipeline using Docker TAR exports for BdCommerce SaaS, eliminating build-step failures and guaranteeing consistent environments.

🔄 The Zero-Build Workflow

[ Local Machine ]                   [ Target VPS ]
  ├── 1. Build Docker Image
  ├── 2. Export to .tar ──(SCP)──────► 4. Load .tar
  └── 3. Upload File                  └── 5. docker compose up
Enter fullscreen mode Exit fullscreen mode
  1. Build & Export (Local Workstation) First, build your production-ready image locally.

⚠️ Critical for Next.js: Variables prefixed with NEXT_PUBLIC_ are baked into the build output at compile time. Changing them requires a full rebuild.

# Step 1: Build the production image
docker build -t bdcommerce_saas_panel:prod .

# Step 2: Export to a transferable archive
docker save -o bdcommerce_saas_panel.tar bdcommerce_saas_panel:prod

# Step 3: Transfer to target server
scp bdcommerce_saas_panel.tar poran@yourip:/home/frontend/bdcommerce-saas-panel/
Enter fullscreen mode Exit fullscreen mode
  1. Load & Deploy (Production VPS) Connect to your VPS and swap the old image with the newly imported artifact without rebuilding a single line of code. 
# Step 1: SSH into server
ssh poran@5.125.580.40

# Step 2: Navigate to project workspace
cd /home/frontend/bdcommerce-saas-panel

# Step 3: Import image into local Docker registry
docker load -i bdcommerce_saas_panel.tar

# Step 4: Recreate containers with new image
docker compose up -d --force-recreate

# Step 5: Clean up archive to save disk space (Optional)
rm bdcommerce_saas_panel.tar
Enter fullscreen mode Exit fullscreen mode

🔍 Verification & Health Checks
Verify your deployment and monitor logs immediately after firing up the container:

# Verify running state
docker ps

# Stream logs to ensure no runtime runtime crashes
docker logs bdcommerce_saas_panel -f
Enter fullscreen mode Exit fullscreen mode

🛠️ Troubleshooting & Caveats
🔹 The Trailing Slash Pitfall
If your API calls fail or fail authentication silently:

❌ NEXT_PUBLIC_API_BASE_URL=https://api.bdcommerce.app/

✅ NEXT_PUBLIC_API_BASE_URL=https://api.bdcommerce.app

🔹 Cloudflare / CDN Stale Cache
If UI changes do not appear post-deploy:

Open Cloudflare Dashboard ➔ Caching ➔ Purge Everything.

Force-refresh browser cache (Ctrl + Shift + R or Cmd + Shift + R).

💡 Why This Approach Works
Zero Resource Spikes: Low-tier VPS nodes never run out of RAM during npm run build.

Predictability: What you run and test locally is identically what executes on production.

Instant Rollbacks: Rolling back is as simple as re-loading a previously saved .tar image.

👨‍💻 About the Author
Name: JAKER HOSSAIN
Username: @jackfd120
Role: Senior Frontend Developer
Portfolio: https://poran-portfolio.up.railway.app

Top comments (0)