Quickstart Guide

Get Your Store Running

This guide will walk you through setting up a complete PixelTech Colombia e-commerce store on Firebase. You’ll configure Firebase services, deploy the application, and add your first product.

Create Firebase Project

Start by creating a new Firebase project in the Firebase Console.

Click Add Project
Enter your project name (e.g., “pixeltech-store”)
Choose whether to enable Google Analytics (recommended)
Click Create Project

Firebase offers a generous free tier that’s perfect for getting started. You can scale up as your store grows.

Enable Firebase Services

Enable the required Firebase services for your store:

Authentication

Go to Authentication → Get Started
Enable Email/Password sign-in method
Enable Google sign-in method (optional but recommended)

Firestore Database

Go to Firestore Database → Create Database
Start in Production Mode
Choose your region (select closest to Colombia: us-east1 or southamerica-east1)

Cloud Storage

Go to Storage → Get Started
Start in Production Mode
Use the same region as Firestore

Cloud Functions

Go to Functions → Get Started
Upgrade to Blaze (Pay as you go) plan
Enable Cloud Functions API

Cloud Functions requires a billing account, but Firebase’s free tier includes:

2M function invocations/month
400,000 GB-seconds compute time
200,000 CPU-seconds compute time

Hosting

Go to Hosting → Get Started
Follow the setup wizard

Clone and Configure

Clone the PixelTech repository and configure your Firebase project.

Terminal

# Clone the repository
git clone <your-repo-url>
cd pixeltech-colombia

# Install Firebase CLI
npm install -g firebase-tools

# Login to Firebase
firebase login

# Initialize Firebase in your project
firebase init

When prompted, select:

Firestore: Yes
Functions: Yes (Node.js 24)
Hosting: Yes
Storage: Yes

Update Firebase Configuration

Get your Firebase config from the Firebase Console:

Go to Project Settings → General
Scroll to “Your apps” → Web app
Copy the configuration object

Update public/js/firebase-init.js with your credentials:

public/js/firebase-init.js

const firebaseConfig = {
  apiKey: "your-api-key",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.firebasestorage.app",
  messagingSenderId: "your-sender-id",
  appId: "your-app-id",
  measurementId: "your-measurement-id"
};

Keep your Firebase configuration secure. Never commit sensitive credentials to public repositories.

Deploy Firestore Rules

Set up security rules to protect your data.The platform includes comprehensive security rules in firestore.rules:

firestore.rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    
    // Helper functions
    function isAdmin() {
      return request.auth != null && 
        exists(/databases/$(database)/documents/users/$(request.auth.uid)) &&
        get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
    }

    function isOwner(userId) {
      return request.auth != null && request.auth.uid == userId;
    }

    // Products: Public read, admin write
    match /products/{productId} {
      allow read: if true;
      allow create, delete: if isAdmin();
      allow update: if isAdmin();
      
      // Allow stock updates from authenticated users
      allow update: if request.auth != null && 
        request.resource.data.diff(resource.data).affectedKeys()
        .hasOnly(['stock', 'combinations', 'updatedAt']);
    }

    // Orders: Create with validation
    match /orders/{orderId} {
      allow create: if request.resource.data.total > 0 && 
                      request.resource.data.items is list;
      allow read: if isAdmin() || 
                    (request.auth != null && resource.data.userId == request.auth.uid);
      allow update, delete: if isAdmin();
    }

    // Users and their addresses
    match /users/{userId} {
      allow read, write: if isOwner(userId) || isAdmin();
      
      match /addresses/{addressId} {
        allow read, write: if isOwner(userId) || isAdmin();
      }
    }
  }
}

Deploy the rules:

Terminal

firebase deploy --only firestore:rules
firebase deploy --only storage:rules

The security rules ensure that:

Anyone can browse products
Only authenticated users can create orders
Users can only access their own orders and data
Admins have full access to all resources

Configure Environment Variables

Set up environment variables for Cloud Functions.Create functions/.env file:

functions/.env

# MercadoPago Integration
MP_ACCESS_TOKEN=your_mercadopago_access_token

# Email Notifications (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_EMAIL=[email protected]
SMTP_PASSWORD=your_app_password

# ADDI Integration (Optional)
ADDI_CLIENT_ID=your_addi_client_id
ADDI_CLIENT_SECRET=your_addi_client_secret
ADDI_API_URL=https://api.addi.com

# Sistecrédito Integration (Optional)
SISTECREDITO_API_KEY=your_sistecredito_key

# WhatsApp Business API (Optional)
WHATSAPP_API_TOKEN=your_whatsapp_token
WHATSAPP_PHONE_ID=your_phone_number_id

Never commit .env files to version control! Add functions/.env to your .gitignore.

Getting Payment Gateway Credentials

MercadoPago (Required for online payments):

Create account at MercadoPago Developers
Go to “Your integrations” → “Credentials”
Copy your Production Access Token

ADDI (Optional - Buy Now Pay Later):

Contact ADDI Colombia for merchant onboarding
Receive API credentials after approval

Deploy Cloud Functions

Deploy the serverless backend functions.

Terminal

# Install function dependencies
cd functions
npm install
cd ..

# Deploy all functions
firebase deploy --only functions

This deploys:

Payment processing: MercadoPago, ADDI, Sistecrédito
Order management: Email notifications, webhooks
Automated tasks: Cleanup, scheduled transfers
Integrations: WhatsApp, Google Merchant Feed, sitemap

The first deployment takes 5-10 minutes. Subsequent deployments are faster.

Verify deployment:

Terminal

firebase functions:list

You should see:

✔ createMercadoPagoPreference
✔ mercadoPagoWebhook
✔ createCODOrder
✔ sendOrderConfirmation
✔ cleanupOldOrders
✔ touchProductTimestamp
... and more

Deploy the Frontend

Deploy your store’s frontend to Firebase Hosting.

Terminal

# Build your Tailwind CSS (if using)
npm run dev

# Deploy to Firebase Hosting
firebase deploy --only hosting

Your store will be live at:

https://your-project-id.web.app

You can configure a custom domain in Hosting → Add custom domain in the Firebase Console.

Create Your First Admin User

Create an admin account to manage your store.

Go to your deployed site
Click Register and create an account
Go to Firebase Console → Firestore Database
Find the users collection
Find your user document and click to edit
Add a field: role (string) = admin
Save the document

The admin role grants access to:

Product management
Order processing
Customer management
Inventory tracking
Financial reports

Now log out and log back in to access the admin panel at /admin/products.html.

Add Your First Product

Add a product to your catalog through the admin panel.

Navigate to Admin Panel → Products
Click Create Product
Fill in the product details:

Product Data Example

{
  "name": "iPhone 15 Pro Max",
  "brand": "Apple",
  "category": "smartphones",
  "price": 5499000,
  "originalPrice": 5999000,
  "stock": 10,
  "status": "active",
  "description": "Latest iPhone with titanium design and A17 Pro chip",
  "colors": ["Natural Titanium", "Blue Titanium", "Black Titanium"],
  "capacities": ["256GB", "512GB", "1TB"],
  "combinations": [
    {
      "color": "Natural Titanium",
      "capacity": "256GB",
      "stock": 5,
      "sku": "IPH15PM-NT-256"
    },
    {
      "color": "Blue Titanium",
      "capacity": "512GB",
      "stock": 3,
      "sku": "IPH15PM-BT-512"
    }
  ],
  "mainImage": "<upload_image_url>",
  "images": ["<image_1>", "<image_2>"]
}

Upload product images
Click Save Product

Use high-quality images (1200x1200px recommended) and include multiple angles of the product.

Configure Store Settings

Set up your store configuration in Firestore.Create a document in the config collection with ID system:

Firestore: config/system

{
  "storeName": "PixelTech Colombia",
  "storeEmail": "[email protected]",
  "storePhone": "+57 300 1234567",
  "currency": "COP",
  "taxRate": 0.19,
  "cacheVersion": 1,
  "freeShippingThreshold": 150000,
  "defaultShippingCost": 15000,
  "enableWhatsApp": true,
  "whatsappNumber": "+573001234567"
}

Create a document in config collection with ID shipping:

Firestore: config/shipping

{
  "freeThreshold": 150000,
  "defaultPrice": 15000,
  "groups": [
    {
      "name": "Bogotá Metro",
      "price": 8000,
      "daysMin": 1,
      "daysMax": 2,
      "cities": ["Bogotá", "Soacha", "Chía", "Cajicá"]
    },
    {
      "name": "Principales Ciudades",
      "price": 15000,
      "daysMin": 2,
      "daysMax": 4,
      "cities": ["Medellín", "Cali", "Barranquilla", "Cartagena"]
    }
  ]
}

Test Your Store

Now that everything is set up, test your store:

Browse Products

Visit your store homepage and verify products are displayed correctly

Add to Cart

Test the shopping cart and checkout flow

Place Test Order

Use MercadoPago test credentials to process a test order

Admin Panel

Next Steps

Architecture Overview

Learn how PixelTech works under the hood

Configure Payments

Set up additional payment methods

Frontend Styling

Customize your store’s appearance with Tailwind CSS

WhatsApp Integration

Enable customer service via WhatsApp

Common Issues

Products not loading

Check Firestore rules: Ensure products have allow read: if trueVerify product status: Products must have status: "active" to appearCheck browser console: Look for Firebase authentication or permission errors

Payment functions failing

Verify environment variables: Check functions/.env has correct credentialsCheck function logs:

firebase functions:log

Test credentials: Use MercadoPago test mode first before production

Images not uploading

Check Storage rules: Verify storage.rules allows authenticated writesCheck file size: Firebase Storage has default limits (5MB for free tier)Verify CORS: Ensure Firebase Storage CORS is configured correctly

Admin panel not accessible

Verify user role: Check Firestore users/{uid} has role: "admin"Clear cache: Log out and log back in to refresh authentication stateCheck security rules: Ensure admin functions check role properly

Need help? Check the Architecture documentation for detailed technical information or review the Firebase documentation for platform-specific issues.

Getting Started

Customer Features

Admin Dashboard

Integrations

Get Your Store Running

Authentication

Firestore Database

Cloud Storage

Cloud Functions

Hosting

Update Firebase Configuration

Getting Payment Gateway Credentials

Test Your Store

Browse Products

Add to Cart

Place Test Order

Admin Panel

Next Steps

Architecture Overview

Configure Payments

Frontend Styling

WhatsApp Integration

Common Issues

Build docs developers (and LLMs) love

Getting Started

Customer Features

Admin Dashboard

Integrations

​Get Your Store Running

​Authentication

​Firestore Database

​Cloud Storage

​Cloud Functions

​Hosting

​Update Firebase Configuration

​Getting Payment Gateway Credentials

​Test Your Store

Browse Products

Add to Cart

Place Test Order

Admin Panel

​Next Steps

Architecture Overview

Configure Payments

Frontend Styling

WhatsApp Integration

​Common Issues

Build docs developers (and LLMs) love

Get Your Store Running

Authentication

Firestore Database

Cloud Storage

Cloud Functions

Hosting

Update Firebase Configuration

Getting Payment Gateway Credentials

Test Your Store

Next Steps

Common Issues