🚀 Complete Project Setup Guide

Step-by-step instructions to deploy an Astro + Firebase website with automated GitHub Actions CI/CD

⏱️ Estimated time: 30-45 minutes

📋 Prerequisites

Required Accounts

Required Software

1

Download & Setup Template

Actions to take:

  1. Go to vibecoding.cc
  2. Download the Astro + Firebase template
  3. Extract files to your project folder
  4. Open the project folder in Cursor (File → Open Folder)
  5. Open the Terminal panel in Cursor (View → Terminal or Ctrl+`)

✅ Checkpoint: You should have the project folder open in Cursor with Astro files visible in the file explorer

2

Initialize Git Repository

Initialize Git (in Cursor terminal):

git init

Verify .gitignore file:

Make sure your project has a proper .gitignore file that excludes:

  • node_modules/
  • dist/
  • .env
  • .astro/
  • .DS_Store

The VibeCoding template should include this automatically, but verify it exists in your project root.

Create GitHub repository and connect (using Cursor UI):

  1. Go to GitHub.com and create a new repository
  2. In Cursor, open the Source Control panel (View → Source Control or Ctrl+Shift+G)
  3. Click the "+" button next to files to stage them (or click the "+" next to "Changes" to stage all)
  4. Type commit message: "Initial commit"
  5. Click "Commit" button
  6. Click "Publish Branch" button
  7. Select "GitHub" as remote
  8. Choose your repository and click "Publish"

✅ Checkpoint: Code is pushed to GitHub repository

3

Create Firebase Project

Actions to take:

  1. Go to Firebase Console
  2. Click "Create a project"
  3. Enter project name (e.g., "prj-setup-guide")
  4. Enable Google Analytics (optional)
  5. Click "Create project"
  6. Go to "Hosting" in the left sidebar
  7. Click "Get started"

✅ Checkpoint: Firebase project created with Hosting enabled

4

Initialize Firebase in Project

Run these commands in Cursor/VS Code terminal:

firebase login
firebase init

⚠️ Important: When prompted:

  • Select "Hosting"
  • Choose "Use an existing project"
  • Select your Firebase project
  • Set public directory to "dist"
  • Configure as single-page app: Yes
  • Set up automatic builds: Yes
  • Choose GitHub repository
  • Select "Deploy on merge"

⚠️ Important: This process does NOT automatically add service account keys to GitHub. You'll need to manually add the service account key in the next step.

✅ Checkpoint: Firebase initialized with GitHub Actions workflow

5

Configure Environment Variables

Create .env file:

# Copy .env.example to .env
cp .env.example .env
# Edit .env with your Firebase config

Get Firebase config from Console:

  1. Go to Project Settings → General
  2. Scroll down to "Your apps"
  3. Click "Web app" icon
  4. Copy the config values to your .env file

✅ Checkpoint: .env file configured with Firebase credentials

6

Set Up GitHub Secrets

Add Firebase Service Account Key:

  1. Go to Firebase Console → Project Settings → Service Accounts
  2. Click "Generate new private key" and download the JSON file
  3. Go to GitHub repository → Settings → Secrets and variables → Actions
  4. Click "New repository secret"
  5. Name: FIREBASE_SERVICE_ACCOUNT_KEY
  6. Value: Copy and paste the entire JSON content from the downloaded file
  7. Click "Add secret"

Add Environment Variables as Secrets:

Also add these repository secrets (from your .env file):

  • VITE_FIREBASE_API_KEY
  • VITE_FIREBASE_AUTH_DOMAIN
  • VITE_FIREBASE_PROJECT_ID
  • VITE_FIREBASE_MESSAGING_SENDER_ID
  • VITE_FIREBASE_APP_ID

✅ Checkpoint: All secrets configured in GitHub

7

Test & Deploy

Test locally first (in Cursor/VS Code terminal):

npm install
npm run dev

Visit http://localhost:4321 to preview your site in development mode

Test production build:

npm run build
npm run firebase:serve

Visit http://localhost:5002 to preview the production build

Deploy to production (using Cursor Git panel):

  1. Open the Source Control panel in Cursor (View → Source Control or Ctrl+Shift+G)
  2. Stage all changes by clicking the "+" next to "Changes"
  3. Type commit message: "Configure deployment"
  4. Click "Commit" button
  5. Click the "Sync Changes" button (or "Push" if available)

This will trigger the GitHub Actions workflow and deploy your site!

✅ Checkpoint: Website deployed and accessible via Firebase URL

8

Verify Deployment

Check these items:

  • GitHub Actions workflow completed successfully
  • Firebase Hosting shows your deployed site
  • Website loads correctly at Firebase URL (e.g., https://prj-setup-guide.web.app)
  • All pages and features work as expected

🎉 Success! Your website is live with automated CI/CD!

🎯 Next Steps (Optional)

Immediate

  • • Set up custom domain via Firebase Console
  • • Configure Cloudflare DNS settings
  • • Add SSL certificate (automatic with Firebase)

Cursor/VS Code Enhancements

  • • Install useful Cursor extensions (Astro, Tailwind, Firebase)
  • • Install npm metacoding package: npm install -g @metacoding/cli
  • • Create more pages using Cursor's AI assistance
  • • Use Cursor's AI to generate components
  • • Set up Cursor workspace settings for the project

Future Development

  • • Add Firebase Authentication
  • • Implement Firestore database
  • • Set up analytics and monitoring
  • • Add more interactive features

🔧 Troubleshooting

Build fails in GitHub Actions

Check that all environment variables are set correctly in repository secrets

Firebase deployment fails

Verify service account key is valid and has proper permissions

Website shows blank page

Check that Firebase hosting is pointing to 'dist' directory, not 'public'