Setup Wizard

The Setup Wizard provides an interactive, step-by-step deployment experience for the Temp-Number App.

What is the Setup Wizard?

The Setup Wizard is an intelligent deployment script that:

✅ Collects configuration through interactive prompts
✅ Validates your environment and prerequisites
✅ Configures Firebase and GCP projects as needed
✅ Deploys to your chosen platform (Docker or Google Cloud)
✅ Provides clear instructions for post-deployment tasks
✅ Handles errors gracefully with helpful messages

Prerequisites

Before running the wizard, ensure you have:

Required

Platfone Account: Get API credentials
Google account: for access to Firebase Console
Git: For cloning the repository

For Local Deployment

Docker: Version 20.x or higher
Docker Compose: Version 2.x or higher

For Google Cloud Deployment

Google Cloud Account: With billing enabled
gcloud CLI: Install instructions
Domain Name: (Optional) For custom domain setup

🚀 Getting Started

Step 1: Clone the Repository

git clone https://github.com/platfone-com/temp-number-deploy.git
cd temp-number-deploy

Step 2: Run the Setup Wizard

./setup-wizard.sh

The wizard will start and guide you through the entire process.

Windows

Windows users: please refer to Windows Subsystem for Linux (WSL) guide.

▶️ Demonstration Videos

Docker deploy demo

Google Cloud deploy demo

Wizard Flow

Step 1: Welcome Screen

The wizard displays a welcome message and overview of what it will do.

==========================================
  🚀 Temp Number - Setup Wizard
==========================================

This wizard will guide you through setting up the Temp Number application.
You can run it locally using Docker Compose or deploy it to Google Cloud.

Press Enter to continue...

Action: Press Enter to proceed.

Step 2: Select Deployment Target

Choose where you want to deploy the application.

==========================================
  Step 1: Select Deployment Target
==========================================

Where would you like to deploy the application?

1) Local Development (Docker Compose)
   - Runs on your local machine
   - Requires: Docker and Docker Compose
   - Best for: Development and testing

2) Google Cloud Platform (Cloud Run)
   - Hosted in the cloud
   - Requires: GCP project with billing enabled
   - Best for: Production deployment

Enter your choice [1-2]: 2
✓ Selected: Google Cloud Platform

Options:

1 - Local Development: Runs the full stack on your local machine using Docker Compose
2 - Google Cloud Platform: Deploys to GCP using Cloud Run and CloudSQL

Recommendation:

Use Local for development, testing, and learning
Use GCP for production deployments with scalability

Step 3: Select Components to Deploy

(Local deployments only) Choose which components to include:

==========================================
  Step 1b: Select Components to Deploy
==========================================

Which components would you like to deploy?

1) Full Stack (Database + Backend + Web Frontend)
   - Complete application with web interface
   - Best for: Full-stack deployment

2) Backend + Database Only (No Web Frontend)
   - API server and database only
   - Best for: Mobile app developers, API-only services

3) Web Frontend Only (requires existing Backend)
   - Deploy/update web frontend only
   - Best for: Updating web UI with existing backend

Enter your choice [1-3]: 1
✓ Selected: Full Stack (Database + Backend + Web)

Options:

1 - Full Stack: Deploy complete application (MySQL + Backend + Web)
2 - Backend + Database Only: For mobile developers or API-only use cases
3 - Web Frontend Only: Update or redeploy web interface when backend is running

Note: This step only appears for local Docker deployments. GCP deployments always include all components.

Step 4: Prerequisites Check

The wizard verifies all required tools are installed.

==========================================
  Step 2: Checking Prerequisites
==========================================

✓ gcloud CLI found
✓ Authenticated with gcloud

What it checks:

For all deployments:

gcloud CLI installation
gcloud authentication status

For local deployments only:

Docker installation
Docker Compose availability

If checks fail:

Install missing tools
Authenticate with gcloud if prompted
Re-run the wizard after fixing issues

Step 5: Source Code Repositories

The wizard checks if source code repositories are present and offers to clone them.

==========================================
  Step 2b: Checking Source Code Repositories
==========================================

✓ Backend repository found
✓ Web repository found

What it does:

Checks for temp-number-backend/ directory
Checks for temp-number-web/ directory
Offers to clone missing repositories if not found

If repositories are missing:

⚠ Backend repository (temp-number-backend) not found
⚠ Web repository (temp-number-web) not found

Missing repositories: temp-number-backend temp-number-web

These repositories contain the application source code and are required.

Would you like to clone the missing repositories now? (y/n):

Options:

y - Automatically clone repositories using git
n - Skip and clone manually later

If you choose ‘y’: The wizard will run:

git clone https://github.com/platfone-com/temp-number-backend.git
git clone https://github.com/platfone-com/temp-number-web.git

Step 6: Firebase Project Setup

Firebase is required for all deployments (authentication).

==========================================
  Step 3: Firebase Project Setup
==========================================

Firebase is required for user authentication.

Choose how to configure Firebase:
1) I have an existing Firebase project configured (provide key manually)
2) Set up a new or configure existing Firebase project (via GCP)

Enter your choice [1-2]: 2
ℹ Setting up new GCP project and Firebase...

The wizard now offers two options for Firebase setup:

Option 1: Manual Firebase Key (Existing Project)

Use this option if you already have a Firebase project configured. This allows you to start without billing enabled.

If you answer ‘1’ (manual key for existing Firebase project):

Please download the Firebase Admin SDK key manually:
1. Go to Firebase Console: https://console.firebase.google.com/
2. Select your project
3. Go to Project Settings > Service Accounts
4. Click 'Generate New Private Key'
5. Save the file as: /path/to/config/secrets/firebase-service-account.json

Press Enter when you have downloaded the key...

Steps:

Visit Firebase Console
Select your project
Navigate to Project Settings (gear icon) → Service Accounts
Click Generate New Private Key
Download the JSON file
Save it as: config/secrets/firebase-service-account.json
Press Enter in the wizard

The wizard will:

Verify the file exists
Extract the project ID from the key
Continue with setup

Option 2: Automated GCP & Firebase Setup

If you answer ‘2’ (automated setup via GCP), the wizard will guide you through a complete GCP and Firebase setup:

GCP Project Creation

==========================================
  GCP Project Setup for Temp Number
==========================================

Select GCP Project:

1) Use existing project
2) Create new project

Enter choice [1-2]: 2
Enter new project ID (lowercase, hyphens allowed): temp-number
Enter project name [default: temp-number]:

ℹ Creating project 'temp-number'...
Create in progress for [https://cloudresourcemanager.googleapis.com/v1/projects/temp-number].
Waiting for [operations/create_project.global.8107866941552596405] to finish...done.
Enabling service [cloudapis.googleapis.com] on project [temp-number]...
Operation "operations/acat.p2-832601501946-408b1370-d5d2-46c4-84f1-012d142dc397" finished successfully.
INFORMATION: Project 'temp-number' has no 'environment' tag set. Use either 'Production', 'Development', 'Test', or 'Staging'. Add an 'environment' tag using `gcloud resource-manager tags bindings create`.

✓ Project created
Updated property [core/project].
✓ Active project: temp-number

The wizard will:

Create a new GCP project with your chosen ID
Set it as the active project
Check and enable billing
Enable all required APIs
Create a service account with necessary permissions
Download the service account key

Billing Configuration

==========================================
  Checking Billing
==========================================

ℹ Ensuring Cloud Billing API is enabled...
✓ Cloud Billing API is enabled

billingAccountName: ''
billingEnabled: false
name: projects/temp-number/billingInfo
projectId: temp-number

ℹ Checking billing status...
⚠ Billing is not enabled for this project

ℹ Fetching available billing accounts...
Available billing accounts:

1) Firebase Payment
   ID: 012345-67890AB-CDEFG

Select billing account [1-1]: 1
ℹ Linking project to billing account: Firebase Payment
billingAccountName: billingAccounts/012345-67890AB-CDEFG
billingEnabled: true
name: projects/temp-number/billingInfo
projectId: temp-number

✓ Billing account linked successfully

API Enablement

For local Docker deployments, API enablement is skipped:

ℹ Skipping API enablement (--skip-apis)

ℹ Skipping service account setup (--skip-service-account)

For GCP cloud deployments, the wizard automatically enables all required APIs:

==========================================
  Enabling Required APIs
==========================================

ℹ Enabling cloudbuild.googleapis.com...
✓ cloudbuild.googleapis.com enabled
ℹ Enabling run.googleapis.com...
✓ run.googleapis.com enabled
ℹ Enabling sqladmin.googleapis.com...
✓ sqladmin.googleapis.com enabled
ℹ Enabling secretmanager.googleapis.com...
✓ secretmanager.googleapis.com enabled
ℹ Enabling artifactregistry.googleapis.com...
✓ artifactregistry.googleapis.com enabled

Service Account Creation

For local Docker deployments, service account creation is skipped:

==========================================
  Setup Summary
==========================================

✓ Setup completed successfully!

Project Details:
  • Project ID: temp-number
  • Service Account: Skipped

Service Account Key:
  ℹ GCP Service Account: Skipped

Next Steps:
GCP project created.

1. Set up Firebase Authentication:
   ./setup_firebase_project.sh --project-id temp-number

2. For cloud deployment later, enable required APIs and service account:
   ./setup_gcp_project.sh --project-id temp-number

For GCP cloud deployments, the wizard creates a service account:

==========================================
  Creating Service Account
==========================================

ℹ Creating service account 'temp-number-deployer'...
✓ Service account created

==========================================
  Granting IAM Roles
==========================================

ℹ Granting roles/cloudsql.admin...
✓ roles/cloudsql.admin granted
ℹ Granting roles/run.admin...
✓ roles/run.admin granted
ℹ Granting roles/secretmanager.admin...
✓ roles/secretmanager.admin granted

The service account is granted these roles (GCP deployments only):

roles/cloudsql.admin - Manage CloudSQL databases
roles/cloudbuild.builds.editor - Build container images
roles/run.admin - Deploy Cloud Run services
roles/storage.admin - Access Cloud Storage
roles/iam.serviceAccountUser - Act as service accounts
roles/artifactregistry.admin - Manage container registry
roles/secretmanager.admin - Manage secrets

Firebase Setup

After GCP project setup, the wizard configures Firebase:

✓ GCP project setup complete: temp-number

ℹ Setting up Firebase for project: temp-number

==========================================
  Firebase Project Setup
==========================================

ℹ Setting GCP project: temp-number
ℹ Configuring quota project for Application Default Credentials...
ℹ Using current gcloud authentication
ℹ Active account: [email protected]

==========================================
  Enabling Required APIs
==========================================

ℹ Enabling firebase.googleapis.com...
✓ firebase.googleapis.com enabled
ℹ Enabling identitytoolkit.googleapis.com...
✓ identitytoolkit.googleapis.com enabled
ℹ Enabling serviceusage.googleapis.com...
✓ serviceusage.googleapis.com enabled
ℹ Enabling cloudresourcemanager.googleapis.com...
✓ cloudresourcemanager.googleapis.com enabled
✓ All APIs enabled successfully

==========================================
  Adding Firebase to Project
==========================================

✓ Firebase added to project successfully

==========================================
  Initializing Firebase Authentication
==========================================

✓ Firebase Auth initialized successfully

Firebase Web App Creation

==========================================
  Initializing Firebase Web App
==========================================

ℹ Checking for existing web apps...
ℹ Creating new Firebase web app...
ℹ Web app creation started (operation: operations/workflows/NjE3MGNmZWItYTRkMC00YzJkLWE0MjEtM2M2ZDQ4MTlmY2Iw)
ℹ Waiting for operation to complete...
ℹ Still waiting... (attempt 1/20)
✓ Operation completed
✓ Firebase web app created: 1:832601501946:web:0d4619583ad7a6382f1943
ℹ Waiting for app configuration to be ready...
ℹ Retrieving web app configuration...

✓ Firebase Web App Created Successfully!

==========================================
  🔥 Firebase Web App Configuration
==========================================

ℹ Firebase SDK values retrieved and will be validated/populated automatically.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

VITE_FIREBASE_WEB_API_KEY=AIzaSyCUjyD24gCCv3R6U743Gdioo0s-f5BXXKw
VITE_FIREBASE_AUTH_DOMAIN=temp-number.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=temp-number
VITE_FIREBASE_APP_ID=1:832601501946:web:0d4619583ad7a6382f1943

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Automatic Configuration

The Firebase SDK values are now automatically populated in your web.env file. The wizard will validate and update the configuration file for you.

Authentication Provider Configuration

==========================================
  Authentication Provider Configuration
==========================================

Which authentication providers would you like to enable?

Enable Email/Password authentication? (y/n) [default: y]:
Enable Google OAuth? (y/n) [default: n]:
Enable Apple OAuth? (y/n) [default: n]:
Enable Facebook OAuth? (y/n) [default: n]:

==========================================
  Configuring Sign-In Methods
==========================================

ℹ   → Email/Password: enabled (password required: true)
✓ Sign-in methods configured successfully

Authorized Domains

==========================================
  Configuring Authorized Domains
==========================================

ℹ Fetching existing authorized domains...
ℹ No existing domains found
ℹ Authorized domains to be configured:
  • localhost
  • temp-number.firebaseapp.com
  • temp-number.web.app

✓ Authorized domains configured successfully

Firebase Admin SDK Key

==========================================
  Downloading Firebase Admin SDK Key
==========================================

ℹ Looking for Firebase Admin SDK service account...
ℹ Attempt 1/12: Service account not found yet, waiting 5 seconds...
✓ Found Firebase service account: [email protected]
ℹ Creating service account key...
ℹ Attempt 1/5: Service account not fully provisioned yet, waiting 10 seconds...
✓ Key downloaded to: /home/user/temp-number-deploy/config/secrets/firebase-service-account.json
✓ Permissions set to 600

Setup Summary

==========================================
  Setup Summary
==========================================

✓ Setup completed successfully!
ℹ ==========================================

Project: temp-number

Configured Authentication Methods:
  ✓ Email/Password (password required: true)

Firebase Admin SDK Key: /home/user/temp-number-deploy/config/secrets/firebase-service-account.json

Authorized Domains:
  - localhost
  - temp-number.firebaseapp.com
  - temp-number.web.app

Next Steps:
1. Verify Firebase Authentication settings in Firebase Console:
   https://console.firebase.google.com/project/temp-number/authentication/providers

2. Update your backend configuration with Firebase credentials

ℹ For more details, see Firebase Console:
ℹ https://console.firebase.google.com/project/temp-number

✓ Firebase setup complete for project: temp-number

ℹ Skipping GCP service account setup (not needed for local Docker deployment)

Step 7: Configuration Files Check

After Firebase/GCP setup is complete, the wizard verifies all configuration files are present.

==========================================
  Step 5: Configuration Files
==========================================

Checking required configuration files...

⚠ backend.env not found
⚠ web.env not found
⚠ backend.secrets not found
✓ firebase-service-account.json found

ℹ Creating missing configuration files from templates...

✓ Created backend.env from template
✓ Created web.env from template
✓ Created backend.secrets from template

⚠️  IMPORTANT: You need to edit the configuration files with your values

Configuration files that need editing:
  • /home/user/temp-number-deploy/config/env/backend.env
    (Database settings, server config)
  • /home/user/temp-number-deploy/config/env/web.env
    (Firebase config, API URLs)
  • /home/user/temp-number-deploy/config/secrets/backend.secrets
    (API keys, passwords, APP_KEY)

You can edit these files now or later.
The setup cannot continue until these files are properly configured.

Would you like to edit them interactively now? (y/n): y

Interactive Editing:

If you answer y, the wizard opens each configuration file in nano editor for you to edit:

backend.env - Opens in nano for editing
web.env - Opens in nano for editing
backend.secrets - Opens in nano for editing (this is where you set your PLATFONE_API_KEY)

After Editing:

✓ Configuration files edited

==========================================
  Validating Firebase Web Configuration
==========================================

⚠ Firebase SDK values not set in web.env - populating automatically...
ℹ Backed up web.env to: /home/user/temp-number-deploy/config/env/web.env.backup.20251114_160920
✓ Firebase SDK values populated in web.env

ℹ Verifying configuration files...

ℹ Skipping DB_PASSWORD validation for local Docker deployment
ℹ Validating PLATFONE_API_KEY by making test request to https://temp-number-api.com/test/api/v1...
✓ PLATFONE_API_KEY is valid

The wizard now:

Automatically populates Firebase SDK values in web.env (creates a backup first)
Validates your PLATFONE_API_KEY by making a test API request
Skips database password validation for local deployments (uses default)

Minimal Configuration to Launch

For a quick demo build, you only need to set:

In backend.secrets:

PLATFONE_API_KEY - Your Platfone API key

All other values use sensible defaults.

For detailed configuration options, refer to Configuration Guide.

Step 8: Deploy Application

After all prerequisites are complete, the wizard offers to deploy.

ℹ All prerequisites are complete!

Ready to deploy? (y/n): y

For Docker Deployment

If you selected Local Development:

==========================================
  Step 6: Deploy Application
==========================================

ℹ Deploying to local Docker Compose...

ℹ Configuring for local deployment...

ℹ Note: Configuration overrides for Docker deployment:
  - DB_HOST='mysql'
  - DB_PORT=3306
  - DB_PASSWORD=temp_number_password (default if not set in backend.secrets)
  - ALLOWED_ORIGINS='http://localhost:8080'


ℹ Starting Docker Compose...

This will:
  1. Build Docker images
  2. Start MySQL database
  3. Start backend service
  4. Start web frontend
  5. Run database migrations

Press Enter to start deployment...

==========================================
  Docker Compose Local Setup
==========================================

✓ Docker and Docker Compose are installed

ℹ Checking configuration files...
✓ Configuration files exist

✓ Firebase credentials found
ℹ Setting Firebase service account file permissions...
✓ Permissions set (644)

✓ Project directories found

ℹ Creating .env file for Docker Compose...
✓ Configuration loaded from .env file

ℹ Running mode: background (start services in background)
ℹ Starting services in background (profile: full)...

What happens:

The wizard runs ./docker-start.sh
Validates Docker and configuration files
Sets proper permissions on Firebase credentials
Creates Docker Compose .env file
Starts building Docker images for backend and web

Docker Build Output:

[+] Building 5.7s (27/34)
 => [web build 5/7] RUN npx update-browserslist-db@latest && npm install              3.5s
 => => # npm warn exec The following package was not found and will be installed: [email protected]
 => => # Latest version:     1.0.30001754
 => => # Installed version:  1.0.30001698
 => => # Removing old caniuse-lite from lock file
 => => # Installing new caniuse-lite version
 => => # $ npm install caniuse-lite

The build process:

Uses cached layers where possible for faster builds
Downloads and installs npm dependencies
Builds the React frontend application
Creates optimized production images

Success output:

🎉 Deployment complete!

Your application is now running:
  • Web Frontend: http://localhost:8080/app/
  • Backend API:  http://localhost:3333/api
  • MySQL:        localhost:3336

To manage your Docker services (view logs, stop, clean, etc.):
  ./docker-start.sh

For GCP Deployment

If you selected Google Cloud Platform:

Step 6: Deploy Application

Deploying to Google Cloud Platform...

This will:
  1. Create CloudSQL database instance
  2. Deploy backend to Cloud Run
  3. Run database migrations
  4. Deploy web frontend to Cloud Run

Press Enter to start deployment...

What happens:

Runs deploy_app.sh with all parameters
Creates CloudSQL MySQL instance
Deploys backend to Cloud Run
Runs database migrations
Deploys web frontend to Cloud Run
Configures environment variables and secrets

Success output:

✓ 🎉 Deployment complete!

Your application is now deployed to Google Cloud.

To get service URLs:
  gcloud run services describe temp-number-web --region us-central1 --format='value(status.url)'
  gcloud run services describe temp-number-backend --region us-central1 --format='value(status.url)'

To view logs:
  gcloud logging read 'resource.type=cloud_run_revision' --limit 100 --project=temp-number

==========================================
  Step 7: Configuring Firebase Authentication
==========================================

ℹ Checking current Firebase Auth configuration...
ℹ Web deployment: Using frontend URL from web.env
ℹ Callback URL: https://temp-number-web-p4oh4mgzxa-uc.a.run.app/app/deeplink
ℹ Authorized domain: temp-number-web-p4oh4mgzxa-uc.a.run.app
ℹ Setting Firebase Auth callback URL and authorized domain...

Post-Deployment Firebase Configuration:

After GCP deployment completes, the wizard automatically:

Retrieves the Cloud Run service URL for your web frontend
Configures the Firebase Auth callback URL (for deep linking)
Adds the Cloud Run domain to Firebase authorized domains
Updates Firebase Auth settings to work with your deployed application

This ensures Firebase Authentication works correctly with your production deployment.

Automated Deployment

For automated or CI/CD deployments, please refer to:

CI/CD Integration

The setup wizard can be integrated into CI/CD pipelines for automated deployments. Setup wizard outputs commands it runs, which can be scripted in your pipeline.

Troubleshooting

Common Issues

Issue: “Docker not found”

# Install Docker
curl -fsSL https://get.docker.com | sh

Issue: “gcloud not authenticated”

# Authenticate with Google Cloud
gcloud auth login
gcloud auth application-default login

Issue: “Firebase credentials invalid”

Ensure you downloaded the service account JSON from Firebase Console
Check file path is correct and file is readable
Verify the service account has required permissions

Issue: “Platfone API validation failed”

Check your API key is correct
Ensure your Platfone account is active
Verify the API URL is correct

Getting Help

If you encounter issues:

Review deployment output for errors and warnings
Review troubleshooting section above
Contact support at

What’s Next?

After successful deployment:

Configuration

Configure authentication, payments, and more

Development Guide

Customize and extend the application

Local Docker Deployment

Setup Wizard

What is the Setup Wizard?#

Prerequisites#

Required#

For Local Deployment#

For Google Cloud Deployment#

🚀 Getting Started#

Step 1: Clone the Repository#

Step 2: Run the Setup Wizard#

▶️ Demonstration Videos#

Docker deploy demo#

Google Cloud deploy demo#

Wizard Flow#

Step 1: Welcome Screen#

Step 2: Select Deployment Target#

Step 3: Select Components to Deploy#

Step 4: Prerequisites Check#

Step 5: Source Code Repositories#

Step 6: Firebase Project Setup#

Option 1: Manual Firebase Key (Existing Project)#

Option 2: Automated GCP & Firebase Setup#

GCP Project Creation#

Billing Configuration#

API Enablement#

Service Account Creation#

Firebase Setup#

Firebase Web App Creation#

Authentication Provider Configuration#

Authorized Domains#

Firebase Admin SDK Key#

Setup Summary#

Step 7: Configuration Files Check#

Step 8: Deploy Application#

For Docker Deployment#

For GCP Deployment#

Automated Deployment#

Troubleshooting#

Common Issues#

Getting Help#

What’s Next?#

Configuration

Development Guide

What is the Setup Wizard?

Prerequisites

Required

For Local Deployment

For Google Cloud Deployment

🚀 Getting Started

Step 1: Clone the Repository

Step 2: Run the Setup Wizard

▶️ Demonstration Videos

Docker deploy demo

Google Cloud deploy demo

Wizard Flow

Step 1: Welcome Screen

Step 2: Select Deployment Target

Step 3: Select Components to Deploy

Step 4: Prerequisites Check

Step 5: Source Code Repositories

Step 6: Firebase Project Setup

Option 1: Manual Firebase Key (Existing Project)

Option 2: Automated GCP & Firebase Setup

GCP Project Creation

Billing Configuration

API Enablement

Service Account Creation

Firebase Setup

Firebase Web App Creation

Authentication Provider Configuration

Authorized Domains

Firebase Admin SDK Key

Setup Summary

Step 7: Configuration Files Check

Step 8: Deploy Application

For Docker Deployment

For GCP Deployment

Automated Deployment

Troubleshooting

Common Issues

Getting Help

What’s Next?