Skip to main content

Overview

This guide will walk you through deploying your own Hive instance. Hive is designed to be easy to deploy on modern serverless platforms, with Vercel as the recommended option.
This guide assumes you have basic familiarity with Git, npm, and environment variables. If you’re new to these tools, check out the linked resources.

Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ installed on your machine
  • Git for version control
  • A Supabase account (free tier works great)
  • A Vercel account (free tier recommended for hosting)
  • A GitHub account for code repository

Architecture Overview

1
Step 1: Clone the Repository
2
First, clone the Hive repository from GitHub:
3
SSH
git clone git@github.com:Knill01/PM-Hive.git hive
cd hive
HTTPS
git clone https://github.com/Knill01/PM-Hive.git hive
cd hive
4
Install dependencies:
5
npm
cd frontend
npm install
yarn
cd frontend
yarn install
pnpm
cd frontend
pnpm install
6
Hive uses minimal dependencies—only @supabase/supabase-js for the backend connection.
7
Step 2: Set Up Supabase
8
Supabase provides the backend infrastructure (database, auth, and realtime).
9
2.1 Create a Supabase Project:
10
  • Go to supabase.com and sign in
  • Click “New Project”
  • Choose a name, database password, and region
  • Wait for the project to be provisioned (~2 minutes)
  • 11
    2.2 Configure Database Schema:
    12
    Hive requires several database tables. Run these SQL commands in the Supabase SQL Editor:
    13
    -- Users table (extends Supabase Auth)
    CREATE TABLE usuarios (
      id SERIAL PRIMARY KEY,
      auth_user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
      nombre_usuario TEXT UNIQUE NOT NULL,
      correo TEXT UNIQUE NOT NULL,
      nombre_completo TEXT,
      puesto TEXT,
      cedula TEXT UNIQUE,
      foto_url TEXT,
      ultimo_acceso TIMESTAMPTZ,
      presence_state TEXT DEFAULT 'offline',
      fecha_registro TIMESTAMPTZ DEFAULT NOW()
    );
    
    -- Projects table
    CREATE TABLE proyectos (
      id SERIAL PRIMARY KEY,
      nombre TEXT UNIQUE NOT NULL,
      descripcion TEXT,
      estado TEXT DEFAULT 'activo',
      fecha_inicio DATE NOT NULL,
      fecha_fin DATE NOT NULL,
      color TEXT DEFAULT '#ECFDF5',
      opa FLOAT DEFAULT 0.65,
      creador_id INTEGER REFERENCES usuarios(id) ON DELETE SET NULL,
      fecha_creacion TIMESTAMPTZ DEFAULT NOW()
    );
    
    -- Tasks table
    CREATE TABLE tareas (
      id SERIAL PRIMARY KEY,
      titulo TEXT NOT NULL,
      descripcion TEXT,
      estado TEXT DEFAULT 'pendiente',
      prioridad TEXT DEFAULT 'media',
      fecha_vencimiento DATE,
      fecha_creacion TIMESTAMPTZ DEFAULT NOW(),
      porcentaje_completado INTEGER DEFAULT 0,
      proyecto_id INTEGER REFERENCES proyectos(id) ON DELETE CASCADE,
      CHECK (porcentaje_completado >= 0 AND porcentaje_completado <= 100)
    );
    
    -- Tags table
    CREATE TABLE etiquetas (
      id SERIAL PRIMARY KEY,
      nombre TEXT UNIQUE NOT NULL,
      color TEXT DEFAULT '#3B82F6'
    );
    
    -- Task-Tag junction table
    CREATE TABLE tarea_etiquetas (
      tarea_id INTEGER REFERENCES tareas(id) ON DELETE CASCADE,
      etiqueta_id INTEGER REFERENCES etiquetas(id) ON DELETE CASCADE,
      PRIMARY KEY (tarea_id, etiqueta_id)
    );
    
    -- Task-User junction table (assignments)
    CREATE TABLE tarea_usuarios (
      tarea_id INTEGER REFERENCES tareas(id) ON DELETE CASCADE,
      usuario_id INTEGER REFERENCES usuarios(id) ON DELETE CASCADE,
      PRIMARY KEY (tarea_id, usuario_id)
    );
    
    -- Deleted users (ban list)
    CREATE TABLE usuarios_borrados (
      id SERIAL PRIMARY KEY,
      nombre_usuario TEXT,
      correo TEXT,
      fecha_eliminacion TIMESTAMPTZ DEFAULT NOW()
    );
    
    -- Enable Row Level Security
    ALTER TABLE usuarios ENABLE ROW LEVEL SECURITY;
    ALTER TABLE proyectos ENABLE ROW LEVEL SECURITY;
    ALTER TABLE tareas ENABLE ROW LEVEL SECURITY;
    ALTER TABLE etiquetas ENABLE ROW LEVEL SECURITY;
    ALTER TABLE tarea_etiquetas ENABLE ROW LEVEL SECURITY;
    ALTER TABLE tarea_usuarios ENABLE ROW LEVEL SECURITY;
    
    -- RLS Policies (allow authenticated users to read/write)
    CREATE POLICY "Allow authenticated users" ON usuarios
      FOR ALL USING (auth.role() = 'authenticated');
    
    CREATE POLICY "Allow authenticated users" ON proyectos
      FOR ALL USING (auth.role() = 'authenticated');
    
    CREATE POLICY "Allow authenticated users" ON tareas
      FOR ALL USING (auth.role() = 'authenticated');
    
    CREATE POLICY "Allow authenticated users" ON etiquetas
      FOR ALL USING (auth.role() = 'authenticated');
    
    CREATE POLICY "Allow authenticated users" ON tarea_etiquetas
      FOR ALL USING (auth.role() = 'authenticated');
    
    CREATE POLICY "Allow authenticated users" ON tarea_usuarios
      FOR ALL USING (auth.role() = 'authenticated');
    
    14
    Make sure to enable Row Level Security (RLS) to protect your data. The policies above allow any authenticated user to access all data—adjust based on your security requirements.
    15
    2.3 Enable Realtime:
    16
  • Go to Database → Replication in Supabase dashboard
  • Enable replication for these tables:
    • tareas
    • tarea_etiquetas
    • tarea_usuarios
    • proyectos
  • 17
    Realtime replication allows Hive to receive instant updates when data changes in the database.
    18
    2.4 Get Your API Credentials:
    19
  • Go to Settings → API in Supabase dashboard
  • Copy these values:
    • Project URL (e.g., https://xxxxx.supabase.co)
    • anon/public key (starts with eyJ...)
    • service_role key (starts with eyJ...) - ⚠️ Keep this secret!
  • 20
    Step 3: Configure Environment Variables
    21
    Create environment variable configuration for your deployment:
    22
    For Vercel Deployment:
    23
  • Go to your project in Vercel dashboard
  • Navigate to Settings → Environment Variables
  • Add these variables:
  • 24
    VariableValueDescriptionNEXT_PUBLIC_SUPABASE_URLhttps://xxxxx.supabase.coYour Supabase project URLNEXT_PUBLIC_SUPABASE_ANON_KEYeyJ...Your Supabase anon/public keySUPABASE_SERVICE_KEYeyJ...Your Supabase service_role key (⚠️ secret)
    25
    Never commit the service_role key to your Git repository. This key has full database access and should only be used server-side.
    26
    For Local Development:
    27
    The Hive client reads credentials from global variables. You can set them in the browser console or create a .env file:
    28
    // Credentials are read from multiple sources
    const supabaseUrl =
      process.env?.NEXT_PUBLIC_SUPABASE_URL ||
      window.SUPABASE_URL ||
      'https://vcssfbdprqmpmuhwaapb.supabase.co'; // fallback for dev
    
    const supabaseAnonKey =
      process.env?.NEXT_PUBLIC_SUPABASE_ANON_KEY ||
      window.SUPABASE_ANON_KEY ||
      'eyJ...'; // fallback for dev
    
    const supabaseServiceKey =
      process.env?.SUPABASE_SERVICE_KEY ||
      window.SUPABASE_SERVICE_KEY ||
      'eyJ...'; // fallback for dev
    
    // Initialize clients
    const supabase = window.supabase.createClient(
      supabaseUrl,
      supabaseAnonKey
    );
    
    const supabaseAdmin = window.supabase.createClient(
      supabaseUrl,
      supabaseServiceKey
    );
    
    window.__supabaseClient = supabase;
    window.__supabaseAdmin = supabaseAdmin;
    
    29
    For production, always use environment variables. The fallback values in the code are only for local development.
    30
    Step 4: Deploy to Vercel
    31
    Vercel provides free hosting for static sites with serverless functions.
    32
    4.1 Install Vercel CLI:
    33
    npm
    npm install -g vercel
    
    yarn
    yarn global add vercel
    
    pnpm
    pnpm add -g vercel
    
    34
    4.2 Deploy:
    35
    cd frontend
    vercel
    
    36
    Follow the prompts:
    37
  • Link to existing project? → No (first time)
  • Project name?hive (or your choice)
  • Directory containing code?./ (current directory)
  • Override settings? → No
  • 38
    The Vercel CLI will automatically detect your project type and configure build settings.
    39
    4.3 Add Environment Variables:
    40
    After deployment, add your Supabase credentials in the Vercel dashboard (as described in Step 3).
    41
    4.4 Redeploy with Environment Variables:
    42
    vercel --prod
    
    43
    Your Hive instance is now live! 🎉
    44
    Step 5: Create Your First Admin User
    45
    To access your new Hive instance, create an admin user in Supabase:
    46
    5.1 Create Auth User:
    47
  • Go to Authentication → Users in Supabase dashboard
  • Click “Add user”
  • Enter email and password
  • Click “Create user”
  • 48
    5.2 Add User Record:
    49
    Run this SQL in Supabase SQL Editor (replace with your values):
    50
    INSERT INTO usuarios (
      auth_user_id,
      nombre_usuario,
      correo,
      nombre_completo,
      puesto
    ) VALUES (
      'YOUR_AUTH_USER_ID', -- Get this from Authentication → Users
      'admin',
      'admin@yourcompany.com',
      'Admin User',
      'Administrator'
    );
    
    51
    Make sure the auth_user_id matches the UUID from the Supabase Auth user you just created.
    52
    Now you can log in with your email and password!
    53
    Step 6: Configure Additional Settings (Optional)
    54
    Custom Domain:
    55
  • Go to Settings → Domains in Vercel
  • Add your domain (e.g., hive.yourcompany.com)
  • Update DNS records as instructed
  • 56
    Email Notifications:
    57
  • Go to Authentication → Email Templates in Supabase
  • Customize confirmation and reset password emails
  • Configure SMTP settings for custom email domain
  • 58
    Storage for Avatars:
    59
  • Go to Storage in Supabase dashboard
  • Create a bucket named avatars
  • Set permissions to allow authenticated uploads
  • Alternative Deployment Options

    Self-Hosted (Docker)

    Hive can be self-hosted using Docker:
    Dockerfile
    FROM node:18-alpine
    
    WORKDIR /app
    
    COPY frontend/package*.json ./
    RUN npm ci --only=production
    
    COPY frontend/ ./
    
    EXPOSE 3000
    
    CMD ["npx", "http-server", "-p", "3000"]
    
    docker-compose.yml
    version: '3.8'
    
    services:
      hive:
        build: .
        ports:
          - "3000:3000"
        environment:
          - NEXT_PUBLIC_SUPABASE_URL=${SUPABASE_URL}
          - NEXT_PUBLIC_SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
          - SUPABASE_SERVICE_KEY=${SUPABASE_SERVICE_KEY}
    
    Run with:
    docker-compose up -d
    

    Static Hosting (Netlify, Cloudflare Pages)

    Hive’s frontend is entirely static and can be hosted anywhere:
    1. Build the frontend: npm run build (if you have a build script)
    2. Upload the frontend/ directory to your static host
    3. Configure environment variables in the hosting platform

    Troubleshooting

    Supabase Connection Issues

    Problem: “Supabase CDN no cargado” error in console Solution: Make sure the Supabase CDN script is loaded in index.html:
    <script src="https://unpkg.com/@supabase/supabase-js"></script>
    

    Authentication Fails

    Problem: “Usuario o contraseña incorrectos” even with correct credentials Solution: Check these:
    1. Verify the usuarios record has the correct auth_user_id
    2. Make sure the user is not in usuarios_borrados (ban list)
    3. Check RLS policies allow the user to read from usuarios table

    Realtime Not Working

    Problem: Changes don’t appear in real-time Solution:
    1. Verify replication is enabled in Supabase (Database → Replication)
    2. Check browser console for WebSocket errors
    3. Ensure PMH_ENABLE_REALTIME is true in app.js:
    window.PMH_ENABLE_REALTIME = true;
    

    Tasks Not Saving

    Problem: Tasks appear briefly then disappear Solution: Check RLS policies on tareas table. You may need to adjust:
    CREATE POLICY "Allow task creation" ON tareas
      FOR INSERT WITH CHECK (auth.role() = 'authenticated');
    
    CREATE POLICY "Allow task updates" ON tareas
      FOR UPDATE USING (auth.role() = 'authenticated');
    

    Performance Optimization

    Enable Caching

    Configure Vercel edge caching for static assets:
    vercel.json
    {
      "headers": [
        {
          "source": "/css/(.*)",
          "headers": [
            {
              "key": "Cache-Control",
              "value": "public, max-age=31536000, immutable"
            }
          ]
        },
        {
          "source": "/js/(.*)",
          "headers": [
            {
              "key": "Cache-Control",
              "value": "public, max-age=31536000, immutable"
            }
          ]
        }
      ]
    }
    

    Database Indexes

    Add indexes for common queries:
    CREATE INDEX idx_tareas_proyecto_id ON tareas(proyecto_id);
    CREATE INDEX idx_tareas_estado ON tareas(estado);
    CREATE INDEX idx_tarea_usuarios_usuario_id ON tarea_usuarios(usuario_id);
    CREATE INDEX idx_usuarios_auth_user_id ON usuarios(auth_user_id);
    

    Security Best Practices

    Always follow these security guidelines in production:
    1. Never expose service_role key - Only use it server-side in Vercel functions
    2. Use RLS policies - Restrict data access based on user roles
    3. Validate input - Sanitize all user input on the client and server
    4. Enable HTTPS - Vercel provides this automatically
    5. Regular backups - Supabase has automatic backups, but test recovery

    Next Steps

    Your Hive instance is now running! Here’s what to do next:

    Quickstart Guide

    Log in and create your first project

    Authentication Setup

    Configure user roles and permissions

    Environment Config

    Learn about all available environment variables

    Supabase Configuration

    Advanced Supabase setup and optimization

    Getting Help

    If you run into issues:

    Build docs developers (and LLMs) love