Black Swan Bistro - Part 6

The Deployment Model

A deployment is not magic. It is a hand-off from your project files to a public web server. Once you can name each part of that hand-off, you can debug it.

Four terms that prevent most confusion

Choose Your Pathway

You can complete only the pathway that matches your project. Reading both is worthwhile, though: modern deployment is still the same web underneath, wearing more automation.

Student Downloads

Pathway A: Deploy Static HTML Through Traditional Hosting

Traditional hosting usually gives each domain a document root: the folder the web server treats as the public top level of that site. In cPanel-based hosting, a primary domain often uses public_html; an additional domain may use a folder inside it. Confirm the exact document root instead of guessing.

Procedure

1. Prepare a clean release folder. Copy only the public site files: index.html, page files, CSS, JavaScript, images, and any web fonts or icons you actually use.
2. Test the release locally. Use a local server or editor preview and click every navigation link. Avoid relying only on double-clicked file:// URLs.
3. Identify the correct document root. Read it from the hosting control panel. The host controls this location.
4. Back up the current live site. If files already exist, download or compress them before replacing anything.
5. Upload the release. With File Manager, ZIP the release contents, upload, extract, and remove accidental nesting. With SFTP, upload the contents while preserving folders.
6. Load the public URL. Use a private window, confirm HTTPS, and check whether www and non-www behaviour is intentional.

<!-- Relative: works when pages and assets keep this relationship -->
<link rel="stylesheet" href="css/styles.css">

<!-- Root-relative: starts at the deployed domain root -->
<link rel="stylesheet" href="/css/styles.css">

<!-- Local computer path: will fail on the public web -->
<link rel="stylesheet" href="C:\Users\You\Bistro\css\styles.css">

Pathway B: Deploy Vue/Vite Through GitHub

This pathway has three connected layers: your local Vue/Vite project, a GitHub repository that stores source history, and a deployment service that installs dependencies, builds the project, and publishes the result.

Prove the production build locally

From the folder containing package.json, confirm the scripts, install dependencies, build, and preview:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

npm install
npm run build
npm run preview

A standard Vite build creates dist. vite preview is a local production-build preview, not a production server. If npm run build fails, fix that before opening a hosting dashboard.

Keep Git safe

Commit source, configuration, public assets, package.json, and the correct lockfile. Do not commit generated dependencies, generated output, real secret files, or private data. Values exposed to client-side Vite code are visible in the browser bundle; do not treat VITE_ variables as secret.

node_modules/
dist/
.env
.env.*
!.env.example
.DS_Store

Option B1: GitHub Pages

GitHub Pages serves static output. For a Vite project, GitHub Actions installs dependencies, runs the build, uploads dist as a Pages artifact, and deploys that artifact.

1. Set the correct Vite base path

For a repository site at https://YOUR-USERNAME.github.io/YOUR-REPOSITORY/, set base to the repository path. For a user site or custom-domain root, use / or omit base.

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/YOUR-REPOSITORY/',
})

2. Add the Pages workflow

Copy the supplied workflow template to .github/workflows/deploy.yml in the Bistro project. It builds and uploads dist with the permissions needed for Pages deployment. If your production branch is not main, change the workflow trigger.

name: Deploy Black Swan Bistro to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v7
      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: npm
      - name: Install dependencies
        run: npm ci
      - name: Build production site
        run: npm run build
      - name: Configure GitHub Pages
        uses: actions/configure-pages@v6
      - name: Upload built site
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./dist
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

3. Enable Pages and check routing

In GitHub, open Settings -> Pages and set Source to GitHub Actions. Push the workflow and configuration, then inspect the run in Actions.

If the Bistro has no client-side router, no extra fallback is needed. If it uses Vue Router with createWebHistory(), direct visits to nested routes can return a GitHub Pages 404 because the static host looks for a real file at that path. Beginner-friendly options are hash history or a deliberate Pages-specific 404 fallback.

Option B2: Vercel

Vercel connects directly to GitHub. Production-branch pushes create production deployments; supported branches and pull requests can create preview deployments for review before production changes.

Procedure

1. Import the GitHub repository in Vercel and choose the folder containing the Bistro's package.json.
2. Confirm the detected settings: framework preset Vite, build command npm run build, output directory dist, and the intended production branch.
3. Add environment variables only if the project genuinely needs them at build time. Do not use client-side variables for private credentials.
4. Deploy, open the public URL, and use previews for non-production changes when available.

SPA rewrite: conditional, not automatic

If the app uses Vue Router history mode and direct visits to nested routes return 404, add the included vercel.json. This rewrite lets the SPA receive direct requests such as /menu and choose the view client-side. Do not add this blanket rewrite to a true multi-page site.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

The Launch Verification Pass

A green deployment badge means the platform completed its instructions. It does not mean the Bistro is ready for a hungry visitor. Use the downloadable checklist and complete these passes on the public URL.

Troubleshooting by Symptom

What You Have Built

The Black Swan Bistro is now more than a folder on your computer. You identified the browser-ready version of the project, moved it through a deployment pathway, connected files, build output, hosting, and a public URL, and checked the result as a visitor would experience it.

That is the full web-development loop: plan, build, test, deploy, observe, improve.

Technical instructions last verified 4 August 2026. Interfaces and action versions can change, so preserve the concepts and re-check the official resources below when updating this lesson.