cPanel

This guide walks you through deploying WeaveAI on cPanel based shared hosting.

Note

cPanel shared hosting is convenient but may have resource limitations for Node.js applications. For production deployments with higher traffic, consider any of the other Installation options for better performance and scalability.

Prerequisites

Before you begin, ensure you have:

• Web hosting with cPanel as the control panel
• Node.js Selector or Setup Node.js App feature available in cPanel
• PostgreSQL v17 support (check with your hosting provider)
• Domain configured and pointed to your cPanel server
• Terminal access (optional, only needed for npm commands - see alternatives below)

Caution

Not all cPanel hosting providers offer the same features. Contact your hosting provider to confirm Node.js v22 or v24 and PostgreSQL v17 support before proceeding. Some budget shared hosting plans may not support Node.js applications.

This guide primarily uses cPanel’s graphical user interface. Terminal access is only required for running npm commands, but we provide alternatives for users without SSH access.

Install Node.js

cPanel typically provides Node.js through the “Setup Node.js App” feature.

1. Log in to cPanel

2. Navigate to “Setup Node.js App”

3. Create a Node.js application

   • Click “Create Application”
   • Node.js version: Select 22.x or 24.x
   • Application mode: Select Production
   • Application root: Enter the path where you’ll upload your application (e.g. weaveai)
   • Application URL: Select your domain or subdomain
   • Application startup file: Enter build/index.js

4. Click “Create”

Environment Variables

On the same page under Environment variables, add the following variables:

• DATABASE_URL - Add the connection string to your PostgreSQL database (we haven’t created the database yet so leave it empty for now). The format is like this: postgresql://cpanelusername_weaveai_user:password@localhost:5432/cpanelusername_weaveai_db
• AUTH_SECRET - Generate a secret at auth-secret-gen.vercel.app and paste it here
• PUBLIC_ORIGIN - Your domain or sub-domain including the https://
• BODY_SIZE_LIMIT - 104857600

Set Up PostgreSQL Database

Caution

Not all cPanel instances have access to a PostgreSQL database. If you cannot find a PostgreSQL database in your cPanel dashboard, you can choose one of the following options:

• If you have access to WHM, install or enable PostgreSQL for your cPanel instance
• Contact your hosting provider support to enable PostgreSQL for your cPanel instance
• Use a separate database service like Neon, Supabase, etc. instead

1. Navigate to PostgreSQL Databases

   In cPanel, find and click “PostgreSQL Databases” or “PostgreSQL Database Wizard”.

2. Create a new database

   • Database name: Enter a name (e.g., weaveai_db)
   • Click “Create Database”

3. Create a database user

   • Username: Enter a username (e.g., weaveai_user)
   • Password: Generate a strong password
   • Click “Create User”

4. Add user to database

   • Select the user you just created
   • Select the database you created
   • Grant ALL PRIVILEGES
   • Click “Add”

5. Note your database connection details

   You’ll need these for your environment variables:

   • Host: Usually localhost (check cPanel or contact support if unsure)
   • Port: Usually 5432 (default PostgreSQL port)
   • Database name: The name you created (e.g. cpanelusername_weaveai_db)
   • Username: The user you created (e.g. cpanelusername_weaveai_user)
   • Password: The password you set

Note

cPanel typically prefixes database and user names with your cPanel username. The actual names will be shown in the PostgreSQL Databases interface.

Prepare Application Files

1. Create application directory using File Manager

   • In cPanel, find and click “File Manager”
   • Navigate to the app directory that was created when you created the Node.js app
   • Click on “Upload”
   • Upload the WeaveAI .zip file that contains the app files

2. Verify file structure in File Manager

   In the weaveai directory (or whatever you called it when you created the Node.js app), you should see:

   • package.json
   • svelte.config.js
   • Other application files and folders

   Note

   If all files are nested inside an extra folder (e.g., weaveai/weaveai-main/), you’ll need to move them up one level. Select all files, click “Move”, and change the path to remove the extra folder level.

Configure SvelteKit Adapter

WeaveAI must use the Node.js adapter for cPanel deployment. Let’s verify and configure this using File Manager.

1. Open the configuration file in File Manager

   • In cPanel File Manager, navigate to the weaveai directory
   • Locate and click on svelte.config.js
   • Click “Edit” button in the toolbar
   • Click “Edit” again in the confirmation dialog

2. Verify the adapter configuration

   Update your svelte.config.js file on the first line, change adapter-auto to adapter-node:

import adapter from "@sveltejs/adapter-auto"; // change this to @sveltejs/adapter-node
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),

  kit: {
    adapter: adapter(),
  },
};

export default config;

• Click “Save Changes” button
• Click “Close” to return to File Manager

4. Update package.json if adapter is missing

   If @sveltejs/adapter-node wasn’t in the project:

   • In File Manager, open package.json
   • Find the devDependencies section
   • Add this line (maintaining proper JSON formatting):

     "@sveltejs/adapter-node": "^5.0.0",

   • Save the file

   Note

   After updating package.json, you’ll need to run npm install in the next section to install the adapter.

Install Dependencies and Build

This step requires running npm commands. You have two options: build on the server using Terminal, or build locally and upload.

Option A: Build on Server (Requires Terminal Access)

This is the most straightforward approach if you have terminal access.

1. Open Terminal in cPanel

   • In cPanel, find and click “Terminal”
   • You’ll see a command-line interface

2. Navigate to your application directory

   cd ~/weaveai

3. Activate the Node.js environment

   cPanel’s Node.js environment requires activation. The exact command is shown in your “Setup Node.js App” interface. Look for a command like:

   source /home/cpanelusername/nodevenv/weaveai/22/bin/activate

   Update 22 with 24 if you installed Node.js v24. Copy the exact command from your Node.js App page and run it. You should see your terminal prompt change to indicate the Node.js environment is active.

4. Install dependencies - While the the app directory where the files are (e.g. weaveai or whatever you called the directory), run this command:

   npm install

   This may take 3-10 minutes depending on your hosting provider’s resources. Wait for it to complete.

5. Build the application

   npm run build

   This creates the production build in the build/ directory. It may take a few minutes.

Caution

If you encounter memory errors during npm install or build, use Option B below to build locally instead. Shared hosting often has memory limitations that prevent building large applications.

Option B: Build Locally and Upload (No Terminal Required)

If you don’t have terminal access or encounter memory issues, build on your local computer and upload the built files.

1. Build on your local computer

   On your local machine where you have Node.js installed:

   # Navigate to your WeaveAI project
   cd /path/to/weaveai
   
   # Install dependencies
   npm install
   
   # Build for production
   npm run build

2. Prepare files for upload

   You need to upload two things:

   • The build/ directory (production build)
   • The node_modules/ directory (production dependencies)

   Tip

   To reduce upload size, install only production dependencies:

   npm install --production

   This will remove development dependencies you don’t need on the server.

3. Compress the directories

   • Compress build/ into build.zip
   • Compress node_modules/ into node_modules.zip

4. Upload using cPanel File Manager

   • In cPanel File Manager, navigate to weaveai/
   • Click “Upload”
   • Upload build.zip and node_modules.zip
   • After upload completes, return to File Manager
   • Right-click build.zip, select “Extract”, confirm
   • Right-click node_modules.zip, select “Extract”, confirm
   • Delete both .zip files to free space

5. Verify the upload

   In File Manager, verify you now have:

   • build/ directory with index.js inside
   • node_modules/ directory with many package folders

Tip

Recommendation: Most shared hosting environments have limited resources. Building locally (Option B) is often more reliable and faster than building on shared hosting servers.

Push Database Schema

The database schema must be pushed to create all necessary tables. You can do this on the server or locally.

Option A: Push Schema on Server (Requires Terminal)

If you have terminal access and built on the server:

1. Open Terminal and navigate to your app

   cd ~/weaveai
   source /home/cpanelusername/nodevenv/weaveai/22/bin/activate

2. Push the database schema

   npm run db:push

   This creates all necessary database tables and relationships. Confirm when prompted.

Option B: Push Schema Locally (No Server Terminal Required)

Follow the Database Schema guide to push your schema using Drizzle. Once that has been done, come back on this page to finish the guide.

Restart the Node.js app so all of our changes take effect

1. Return to “Setup Node.js App” in cPanel

   Navigate back to the Node.js application manager in cPanel.

2. Edit your application

   Find your WeaveAI application in the list and click “Edit”.

3. Start the application

   Click “Start App” or “Restart” if already running.

Set Up Domain/Subdomain

cPanel’s “Setup Node.js App” feature typically handles domain routing automatically. However, if your application isn’t accessible at your domain, you may need to configure a reverse proxy. Also, keep in mind that your domain needs to have an SSL certificate in order for WeaveAI to function.

Set Up SSL

1. Navigate to SSL/TLS Manager in cPanel

2. Enable SSL for the domain where WeaveAI is installed

3. Restart your Node.js application

Updating WeaveAI

When a new version of WeaveAI is released, you’ll need to update your installation. Choose the method that works best for you.

Method 1: Manual Upload (Recommended for Most Users)

This method doesn’t require terminal access and is the most reliable for shared hosting.

1. Build the update on your local computer

   On your local machine:

   # Navigate to your WeaveAI project
   cd /path/to/weaveai
   
   # Pull latest changes (if using Git)
   git pull origin main
   
   # Install any new dependencies
   npm install
   
   # Build for production
   npm run build
   
   # Install production dependencies only (to reduce upload size)
   npm install --production

2. Backup current installation

   • In cPanel File Manager, navigate to the weaveai directory
   • Right-click the build folder
   • Select “Compress”
   • Save as build-backup-YYYY-MM-DD.zip (use current date)
   • This allows you to restore if something goes wrong

3. Upload updated build

   • On your local computer, compress the new build/ directory to build.zip
   • In cPanel File Manager, navigate to weaveai/
   • Delete the old build/ directory (select it and click “Delete”)
   • Click “Upload” and upload the new build.zip
   • Right-click build.zip, select “Extract”
   • Delete build.zip after extraction

4. Upload updated dependencies (if package.json changed)

   • Compress your updated node_modules/ directory to node_modules.zip
   • In File Manager, delete the old node_modules/ directory
   • Upload and extract node_modules.zip
   • Delete the .zip file

5. Upload any modified source files

   If you’ve made configuration changes or updates to source files:

   • Upload individual files via File Manager or FTP/SFTP
   • Replace the old versions

6. Update database schema (if needed)

   If the update includes database changes:

   • Check the release notes for schema changes
   • On your local machine (with your cPanel database credentials in .env):

     npm run db:push

   • Or use terminal on the server if available

7. Restart the application

   • Navigate to “Setup Node.js App” in cPanel
   • Find your WeaveAI application
   • Click “Restart”

8. Verify the update

   • Visit your application in a browser
   • Check that everything works correctly
   • If there are issues, restore from your backup

Method 2: Using Git and Terminal (For Advanced Users)

This method requires terminal/SSH access and is faster but needs more server resources.

1. Access Terminal

   • In cPanel, open “Terminal”

2. Navigate to your application

   cd ~/weaveai

3. Activate Node.js environment

   source /home/cpanelusername/nodevenv/weaveai/22/bin/activate

4. Backup current build

   cp -r build build-backup-$(date +%Y-%m-%d)

5. Pull latest changes

   git pull origin main

6. Install updated dependencies

   npm install

7. Rebuild the application

   npm run build

8. Update database schema (if needed)

   npm run db:push

9. Restart application

   • Navigate to “Setup Node.js App” in cPanel
   • Click “Restart” on your application