TheBlue v1.5.0

1. Before you install

TheBlue is not a PHP theme. It is a full Node.js application with a MySQL database. On cPanel, the hosting account must provide a persistent Node.js application feature such as Setup Node.js App, Application Manager or Passenger.

Keep these ready before starting:

• Your DevWebThemes TheBlue licence code.
• The same email address used for the DevWebThemes purchase.
• A domain or subdomain already pointed to the hosting account.
• cPanel File Manager and Terminal/SSH access.
• An empty MySQL/MariaDB database and database user.
• Node.js 22 when available.
• At least about 1 GB of available build memory on shared hosting; 2 GB or more is preferred.

2. Server requirements

3. Choose the right hosting

A PHP-only host is not supported. XAMPP can provide MySQL for local development, but TheBlue itself still runs through Node.js.

4. Domain and DNS

5. Create the MySQL database

In cPanel → MySQL Databases or Database Wizard:

1. Create a new empty database.
2. Create a new database user with a long unique password.
3. Add the user to the database.
4. Grant ALL PRIVILEGES to that database.
5. Record the full cPanel-prefixed database name and username.

Example only
Database: cpaneluser_theblue
User:     cpaneluser_theblue
Host:     127.0.0.1
Port:     3306

6. Upload and extract the buyer ZIP

Upload the DevWebThemes buyer ZIP and extract it into a clean application folder in your cPanel home directory, for example:

/home/CPANEL_USER/theblue

The application root must directly contain files such as:

package.json
package-lock.json
server.js
install.sh
next.config.ts
src/
prisma/
public/
scripts/
docs/

Normal Linux permissions are directories 755 and files 644. The installer creates private storage with restrictive permissions when the host supports it.

7. Create the cPanel Node.js application

Open cPanel → Setup Node.js App (the wording can vary by host) and create the application.

After creation, cPanel displays a command for entering the application's virtual environment. Save that command. It normally looks similar to:

source /home/CPANEL_USER/nodevenv/theblue/22/bin/activate && cd /home/CPANEL_USER/theblue

8. CloudLinux: run NPM Install from cPanel first

If your host uses CloudLinux Node.js Selector, click Run NPM Install in the Node.js App screen before running ./install.sh.

CloudLinux stores modules inside the application's virtual environment and exposes them through a symlink named node_modules. TheBlue detects this layout.

node_modules -> /home/CPANEL_USER/nodevenv/theblue/22/lib/node_modules

TheBlue's cPanel install checks for the build packages it needs, including Next.js, Prisma, TypeScript and Tailwind's PostCSS integration.

9. Run the Terminal installer

node -v
npm -v

chmod +x install.sh
./install.sh

The installer checks the dependency lock, detects CloudLinux, validates required packages and launches the guided server setup.

Answer the prompts

What the installer does automatically

1. Creates a protected .env.
2. Generates the session secret, app key, cron secret, install key and stable installation ID.
3. Configures the DevWebThemes activation endpoint and product slug.
4. Creates private storage.
5. Runs server preflight checks.
6. Validates the Prisma schema and generates Prisma Client.
7. Deploys all production database migrations.
8. Builds the production application.
9. Prepares Next.js standalone output.
10. Prints the one-time installation key.

Why the cPanel build is different

TheBlue automatically uses its cPanel-safe build path on CloudLinux. It uses Webpack rather than Turbopack, enables Next.js memory optimizations, limits page-generation build concurrency to one worker, and uses a conservative Node heap target. These choices exist because many shared cPanel servers expose old Linux libraries and strict memory/process limits.

10. Restart and open the browser installer

When the Terminal installer finishes, copy the one-time Installation key. Return to cPanel → Setup Node.js App and click Restart Application.

Then open:

https://YOUR-DOMAIN/install

Installer steps

1. System Checks — Node, database and writable private storage must be green.
2. Purchase Licence — enter the DevWebThemes licence code and the purchase email.
3. Store Details — confirm store name and support/contact email.
4. Admin Account — enter the administrator information, strong password and the one-time installation key printed by Terminal.
5. Complete — the installer activates the licence, creates the admin and locks the installation state.

11. DevWebThemes licence activation

TheBlue is linked to the DevWebThemes licensing service using:

Product slug: theblue
Activation endpoint: https://devwebthemes.com/api/v1/license/activate
Purchase email required: yes

After purchasing, sign into DevWebThemes and open the customer licence area. Copy the TheBlue licence key and use the same purchase email in the installer.

TheBlue submits the licence key, purchase email, product slug, product version, installation domain, environment type and a stable installation ID. DevWebThemes returns an opaque activation token. The buyer package does not contain the marketplace private secret.

The local activation record is stored in:

storage/license.json

12. Immediately after installation

1. Remove INSTALL_TOKEN from .env or the cPanel environment variables.
2. Restart the Node application.
3. Sign in to the administrator account.
4. Open Admin → Settings and replace starter business/contact information.
5. Configure branding, SEO and legal pages.
6. Configure SMTP and send a real test email.
7. Configure payment gateways in sandbox/test mode.
8. Test a full customer journey before going live.
9. Back up the clean installed database and application.

13. Configure scheduled cleanup

Run cleanup at least every 15 minutes. On cPanel, use the Node/npm path provided by your host:

*/15 * * * * cd /home/CPANEL_USER/theblue && /usr/bin/npm run cleanup >/dev/null 2>&1

The cleanup task releases expired exclusive reservations, stale transactions and old rate-limit state. If /usr/bin/npm is not valid on your host, use the executable path from the Node virtual environment.

14. HTTPS, proxy and CDN

• Use HTTPS before accepting logins or payments.
• Keep TRUST_PROXY=true behind cPanel Passenger, Nginx, Caddy or Cloudflare where the forwarded headers are trusted.
• Redirect HTTP to HTTPS at the hosting/proxy layer.
• Do not cache private dashboard, checkout, installer, licence or download responses at a CDN.
• Static /_next/static/ assets can use long cache lifetimes.

15. Configure SMTP email

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=account@example.com
SMTP_PASS=your-secret
SMTP_SECURE=false
SMTP_ALLOW_PLAINTEXT=false
EMAIL_FROM=sales@example.com
EMAIL_FROM_NAME="Your Store"

Use STARTTLS on 587 or implicit TLS on 465 according to the provider. Test registration/password recovery, order emails, invoices, licence emails and support/contact messages.

For deliverability, configure SPF, DKIM and DMARC for the sending domain.

16. Payment gateways

Configure payment credentials from the administration area. Use test/sandbox credentials first. TheBlue's commercial configuration includes support wiring for PayPal, PayChangu, Stripe, Paystack and Flutterwave where enabled in the installed release.

Production checklist

• Use the exact final HTTPS callback/webhook URL.
• Keep secret keys server-side.
• Verify provider signatures/webhooks.
• Confirm amount and currency server-side.
• Test success, cancellation, duplicate webhook, delayed webhook and refund/revocation behaviour.
• Do not accept live payments until the merchant account is fully approved by the provider.

17. Private files and S3-compatible storage

Paid masters must not be exposed as normal public files.

Local private storage

STORAGE_PROVIDER=local
PRIVATE_STORAGE_PATH="/absolute/private/path/storage/private"
MAX_UPLOAD_BYTES=524288000
DEFAULT_MAX_DOWNLOADS=5

S3-compatible storage

STORAGE_PROVIDER=s3
S3_BUCKET=private-beat-masters
S3_REGION=...
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_ENDPOINT=
S3_FORCE_PATH_STYLE=false

Use a private bucket and least-privilege storage credentials. Large masters are better stored outside the web server when the catalogue grows.

18. Administrator first configuration

Before advertising the site, review at least:

• Appearance, logo, colours and typography.
• Homepage sections and hero content.
• Beats, producers and media.
• Licence tiers and legal wording.
• Payment settings.
• Email/SMTP and email branding.
• SEO, Open Graph and PWA assets.
• Legal/policy pages.
• Services, blog, reviews, gallery/video areas as applicable.
• Contact page and admin message inbox.

19. Performance and slower 3G networks

TheBlue is designed around production standalone output, optimized static assets, server-rendered public content, lazy-loading and caching. Hosting and uploaded media still matter.

• Use WebP/AVIF artwork and keep normal cover images small.
• Do not use full WAV masters for public previews. Use compressed tagged preview audio.
• Use a CDN for public static assets.
• Move large private masters to S3-compatible storage when appropriate.
• Avoid unnecessary autoplay video on mobile.
• Use Brotli/gzip at Nginx, Cloudflare, Caddy or the hosting layer.
• Keep the database indexed and avoid unbounded catalogue pages.
• Measure the real live domain using mobile network throttling after each major homepage change.

20. Lifetime product updates

Lifetime updates are product release files. They do not include unlimited custom development, unlimited hosting administration or perpetual managed-service work.

Safe cPanel update flow

1. Back up the database, .env, private storage and uploads.
2. Read the release notes.
3. Extract only the official update/release files as instructed. Never overwrite a live .env with an example.
4. Enter the Node virtual environment.
5. If dependencies changed, use cPanel's Run NPM Install when using CloudLinux Node Selector.
6. Run:

chmod +x scripts/cpanel-build.sh
./scripts/cpanel-build.sh

The cPanel build validates the current environment, applies pending migrations, rebuilds and prepares standalone output. Restart the Node app after completion.

21. Backup and restore

Minimum backup set:

• Full MySQL database export.
• .env stored securely.
• storage/private when using local private storage.
• Runtime public uploads/media.
• Any custom code or custom theme overrides.

Keep at least one backup outside the web server. Test restore procedures before a major update.

22. Linux VPS deployment

For a VPS, use the supplied Nginx/Caddy/systemd/PM2 examples under deployment/. A typical flow is:

npm ci --include=dev --no-audit --no-fund
./install.sh
npm run build
npm run prepare-standalone
npm start

Put Nginx or Caddy in front of the Node process, terminate HTTPS, configure a firewall, enable automatic security updates and use a process manager such as systemd or PM2.

23. Docker deployment

The release includes Dockerfile and docker-compose.yml. Do not copy production secrets into an image layer. Use environment variables or secret management. Back up the external MySQL database and private storage volumes.

24. Windows / local development

Install Node.js 20.9+ and MySQL. XAMPP can provide MySQL, but TheBlue still runs as a Node application.

install.cmd
npm start

Use http://localhost:3000 for local testing. Local/staging activation treatment is determined by the DevWebThemes licence entitlement.

25. Troubleshooting

26. Add-ons and TheBlue Academy

TheBlue v1.5.0 includes a dedicated Add-ons area in the administrator workspace. Add-ons are optional commercial extensions: the core marketplace remains lightweight, while buyers can install only the capabilities their business needs.

Install a purchased add-on

1. Purchase/download the add-on from your DevWebThemes customer account.
2. In TheBlue open Admin → Add-ons.
3. Choose Install Add-on ZIP and select the original add-on ZIP. Do not extract the add-on ZIP first.
4. Enter the add-on licence key and the email used for that add-on purchase.
5. Choose Verify & install. TheBlue validates the package, version compatibility and DevWebThemes entitlement before activation.

TheBlue Academy

TheBlue Academy is the first official feature add-on. Once installed, administrators can create paid or free course products, organize modules and lessons, publish video/text/audio/download lessons, and enable completion certificates. Customers purchase course access through the normal TheBlue checkout and continue learning from Customer Dashboard → My Courses.

Academy and the official payment add-ons are available through the extension catalog. TheBlue v1.5.0 also supports separately licensed Google Login and Email Branding, plus the Growth Essentials Bundle that unlocks both. Google indexing, sitemap.xml, robots.txt and Search Console verification remain core features included with every TheBlue purchase.

27. Google Login, Email Branding & Search Indexing

Google Login add-on

After purchasing and activating the Google Login add-on, open Admin → Add-ons → Google Login. Enter a Google OAuth Web client ID and client secret, add the exact redirect URI shown by TheBlue to the Google Cloud project, and enable the module after testing.

Email Branding add-on

After activation, open Admin → Add-ons → Email Branding to configure the brand name, logo, email colors, support contact/footer and test recipient. The existing SMTP transport remains under the store owner's control.

Growth Essentials Bundle

The Growth Essentials Bundle is one add-on entitlement that unlocks Google Login and Email Branding together. Each module still has its own configuration page.

Google Search indexing is included

Every TheBlue installation includes /sitemap.xml and /robots.txt. Open Admin → Search Indexing to review indexable content counts and Search Console readiness. Sitemap availability helps search engines discover URLs; it is not a guarantee that a search engine will index every page.

27. Commercial pricing, installation and feature requests

Feature requests

You may request a feature from DevWebThemes. Guaranteed custom development, a feature rebuild, or a feature built specifically for your installation starts from USD $250 and increases according to scope.

Verified defects in the unmodified official release are not treated as paid custom feature requests.

Lifetime updates

Buyers receive lifetime access to official TheBlue product updates released for their purchased licence. Each new purchase also includes 6 months of standard product support. Support and update access are separate entitlements. See COMMERCIAL-TERMS.md.

28. How to request support

Before contacting support, collect:

• TheBlue version.
• Hosting provider and hosting type.
• Node.js version.
• MySQL/MariaDB version.
• The exact step that failed.
• Exact error text and a short redacted log excerpt.
• A screenshot when the problem is visual.
• What you have already tried.

Also read SECURITY.md, SUPPORT.md, CHANGELOG.md, COMMERCIAL-TERMS.md and THIRD_PARTY_NOTICES.md.