Deploying Next.js apps tends to get over-engineered fast. For personal sites, dashboards, or internal tools, a straightforward VPS deploy is more than plenty. In this post we’ll set up a small CI/CD pipeline you configure once and then forget about. Every push to main turns into a Docker image, shipped to GitHub’s registry, fetched by your VPS, and swapped in behind Caddy with free HTTPS. --- ## Prerequisites - A VPS with SSH access (domain optional but recommended). - An SSH key pair already set up for the VPS. - Docker & Docker Compose installed on the VPS. - Caddy installed and running as a systemd service. --- ## Initialize the Next.js app We’ll start with a vanilla next.js app. I named the app next-vps-tutorial and also use that as the container name later on: {`npx create-next-app@latest`} --- ## CI/CD overview (the flow we’re building) Here’s the simple pipeline we’ll draft, then implement: {`[git push main] | v [GitHub Actions] Build Next.js image with Docker - Push to GHCR (ghcr.io) | v [SSH into VPS] - docker compose pull - docker compose down && up -d | v [Caddy reverse proxy] - HTTPS by default (Let's Encrypt) - Reverse proxy :443 -> app:3000 | v [page online 🌐]`} --- Let's first dive into the building blocks of the pipeline. The Dockerfile specifies how we build the container in the GitHub Action. The docker-compose.yml defines from which registry we pull the container after it was build. ## Dockerfile We'll build the app in stages, so the final image is lean and ready for production. We only ship what we need to run the server on the VPS. This image will be built by GitHub Actions and run on the VPS. {`# Base image FROM node:22-alpine AS base WORKDIR /app # Stage 1: Install dependencies FROM base AS deps RUN apk add --no-cache libc6-compat COPY package.json package-lock.json* ./ RUN npm ci # Stage 2: Build the app FROM base AS builder COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npm run build # Stage 3: Production image FROM base AS runner WORKDIR /app ENV NODE_ENV=production # disable telemetry during runtime. ENV NEXT_TELEMETRY_DISABLED=1 COPY --from=builder /app ./ EXPOSE 3000 # Next.js port. Default is 3000 ENV PORT=3000 CMD ["npm", "start"]`} ## docker-compose on the VPS Compose defines how the container runs on the server. We’ll listen on port 3000 inside the VPS network; Caddy will proxy to it. Here we also define where we load the image from: `ghcr.io/emirazazi/next-vps-tutorial:latest` points to the image inside the registry. {`services: app: container_name: next-vps-tutorial image: ghcr.io/emirazazi/next-vps-tutorial:latest ports: - "3000:3000" restart: unless-stopped volumes: next_data:`} --- ## GitHub Actions: build & deploy Now we tie everything together with a deploy.yml workflow. This is the bread and butter which defines the pipeline. The workflow mainly does three things: 1) Build and push the image to GHCR using `docker/build-push-action@v5` 2) Copy the docker-compose.yml to the server using `appleboy/scp-action@v1` so we can pull the latest image. 3) SSH into the VPS and restart the container with the latest image using `appleboy/ssh-action@v1.0.0`. {`name: Build and Deploy on: push: branches: [ main ] workflow_dispatch: env: REGISTRY: ghcr.io IMAGE_NAME: \${{ github.repository_owner }}/next-vps-tutorial jobs: build-and-push: name: Build and Push Docker Image runs-on: ubuntu-latest permissions: contents: read packages: write steps: - name: Checkout repository uses: actions/checkout@v4 - name: Log in to GitHub Container Registry uses: docker/login-action@v3 with: registry: \${{ env.REGISTRY }} username: \${{ github.actor }} password: \${{ secrets.GITHUB_TOKEN }} - name: Extract metadata id: meta uses: docker/metadata-action@v5 with: images: \${{ env.REGISTRY }}/\${{ env.IMAGE_NAME }} tags: | type=ref,event=branch type=sha,prefix={{branch}}- type=raw,value=latest,enable={{is_default_branch}} - name: Build and push Docker image uses: docker/build-push-action@v5 with: context: . push: true tags: \${{ steps.meta.outputs.tags }} labels: \${{ steps.meta.outputs.labels }} deploy: name: Deploy to VPS needs: build-and-push runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Copy docker-compose.yml to server uses: appleboy/scp-action@v1 with: host: \${{ secrets.SSH_HOST }} username: \${{ secrets.SSH_USER }} key: \${{ secrets.SSH_PRIVATE_KEY }} source: "docker-compose.yml" target: "\${{ secrets.WORK_DIR }}/" - name: Deploy to VPS via SSH uses: appleboy/ssh-action@v1.0.0 with: host: \${{ secrets.SSH_HOST }} username: \${{ secrets.SSH_USER }} key: \${{ secrets.SSH_PRIVATE_KEY }} script: | cd \${{ secrets.WORK_DIR }} # Log in to GitHub Container Registry echo "\${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u \${{ github.actor }} --password-stdin # Pull the latest image docker compose pull # Stop and remove old container docker compose down # Start new container docker compose up -d # Clean up old images docker image prune -f`} --- ## Repository secrets Before we can start the pipeline we need to insert the credentials through the GitHub UI. Add these to your repo **Settings → Secrets and variables → Actions → Repository Secrets**: {`SSH_HOST: SSH_PRIVATE_KEY: SSH_USER: root WORK_DIR: next-vps-tutorial`} > This way we keep the credentials out of the repo source code while letting the workflow log into the VPS. On the VPS (one-time): {`mkdir -p /root/next-vps-tutorial`} > **Note:** the SCP step can create the target path automatically, but pre-creating avoids permission surprises. Now we can trigger a deployment by pushing to the `main` branch. You should see following Action inside GitHub: ![site up over https](/images/blog/next-vps-tutorial/build_and_deploy.jpg?width=756&height=228) After the first successful deployment, verify: {`docker ps # You should see: next-vps-tutorial ... Up ... 0.0.0.0:3000->3000/tcp`} --- ## Caddy as the HTTPS reverse proxy At this point the container is alive on the VPS, but not yet reachable over HTTP. Caddy will terminate TLS and forward traffic to `localhost:3000`. We’ll use a clean **sites-available / sites-enabled** layout, similar to Nginx. > **Why Caddy:** automatic TLS (Let’s Encrypt), and a tidy config model. If you prefer to use nginx go for it. I won't hold you back. ### Global Caddyfile {`# Global options { email } # Import all enabled site configurations import /etc/caddy/sites-enabled/*.Caddyfile`} ### App Caddyfile Let's now create the config for the app. We expose the next.js server running on port 3000 to the domain: next-vps.tutorial.emirazazi.de. We also set some essential security headers. Create `/etc/caddy/sites-available/next-vps-tutorial.Caddyfile.disabled` with: {`next-vps-tutorial.emirazazi.de { reverse_proxy localhost:3000 { # Disable buffering for Next.js SSR streaming flush_interval -1 } # Essential headers header { X-Content-Type-Options "nosniff" X-Frame-Options "DENY" Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" } # Simple CSP: only self + https resources header { Content-Security-Policy " default-src 'self'; img-src 'self' https:; " } # Enable compression encode gzip } # redirect www to non-www https www.next-vps-tutorial.emirazazi.de { redir https://next-vps-tutorial.emirazazi.de{uri} permanent }`} Enable the site by symlinking the file into `sites-enabled`: {`ln -s ../sites-available/next-vps-tutorial.Caddyfile.disabled /etc/caddy/sites-enabled/next-vps-tutorial.Caddyfile sudo systemctl reload caddy`} > **SSL included by default:** Caddy will automatically obtain and renew a Let’s Encrypt certificate for `next-vps-tutorial.emirazazi.de` as soon as DNS points to your VPS and the site is enabled. No extra steps required. --- ## Congratulations 🏁 You've successfully build a minimal CI/CD pipeline for your Next.js application. *App reachable at https://next-vps-tutorial.emirazazi.de* ![site up over https](/images/blog/next-vps-tutorial/app_running.jpg?width=667&height=571)