Install Guide

Before you start

You'll need four things:

• A cPanel account that can run a Node.js application — either Setup Node.js App (CloudLinux Node.js Selector) or Application Manager (cPanel’s own). Most quality hosts have one or the other; you do not need both, and you do not get to choose which.
• Node.js 22.5 or newer available in the selector. This is required — GWS Backup uses the SQLite engine built into Node 22, and it will not start on Node 20 or older.
• The release files — download them here. Three items: the application payload (-app.zip), the installer (-installer.php) and a README with these same instructions. Each is listed with a SHA-256 so you can check what you got.
• Your free licence key. The software will not run without one. Keys are free — for now they're issued personally, so request yours via the contact form (usually answered within 1–2 days). Automatic key delivery by email is planned for the near future. One key permits one running installation at a time, and validation requires the server to have outbound internet access.

The app itself needs roughly 100 MB of disk and about 50 MB of RAM per client workspace. Your actual backup data is stored in your destination (Google Drive, S3, Azure or local disk) — not on the web server.

Security first: where to install

Fresh installation

1Create the random subdomain

In cPanel → Domains → Create a New Domain (or Subdomains):

• Name: something random, e.g. vault-k7x93q.yourdomain.com
• Document root: a folder outside public_html, e.g. /home/youruser/gwsbackup_web

Then open SSL/TLS Status and run AutoSSL so the subdomain gets a certificate.

2Register the Node.js application

cPanel ships one of two tools for this, and which one you have is decided by your host, not by you. Look in cPanel for whichever of these you can see — the settings are the same either way, only the screen differs.

Whichever screen you are on, the values are:

• Node.js version: 22.x or newer (Route A only — Route B uses the system Node)
• Application mode / environment: Production
• Application root / path: gwsbackup (a folder in your home directory — not inside public_html)
• Application URL / domain: the random subdomain from step 1
• Application startup file: app.js

Create or register the application, then stop it for now — there is nothing to run until the files are in place.

3Upload the application files

In File Manager, open the application root folder (e.g. /home/youruser/gwsbackup) and upload the -app.zip and -installer.php from your download. Then open the cPanel Terminal (or SSH) and run:

Use whichever version you downloaded. The wizard extracts the application, then removes the payload zip and any installer from an earlier release automatically to keep the server clean. No terminal access? Use File Manager's Extract on the -app.zip instead, then delete the zip manually — note that this skips the automatic database backup the installer would have taken first.

4Set the application URL variable

Back in Setup Node.js App (Route A) or Application Manager (Route B), add an environment variable so sign-in and Google callbacks return to the right address:

(your real subdomain, including https://).

5Start the app

Start the application. On first boot it generates its own keys and writes a complete .env in the app folder, including the ENCRYPTION_KEY that protects every credential it will ever store. Back that file up before you go any further. Your recovery key is generated later, inside the app, and shown to you on screen — nothing writes it to the server.

6First-run setup & licence activation

Visit https://your-random-subdomain/ in a browser:

1. Create your administrator account on the setup screen, and save the recovery key it shows you — it is displayed once, and it's the only way back in if you forget your password.
2. You'll then be asked for your licence key. Paste the key we emailed you — no key yet? Request one now; the app will wait on the activation screen until it arrives. The software stays locked until a valid key is activated.
3. Follow the in-app Connection Wizard to link your first Google Workspace — it walks you through the service account and gives you the exact permission scopes to paste into your Google Admin console.

That's it — set your backup schedule and destination in Settings and you're protected.

Updating an existing installation

Updates are one command, and your database is backed up automatically first:

1. Download the latest release from this site.
2. Upload the new -app.zip and its matching -installer.php into your existing application root (the folder containing gws-backup.db).
3. Run:

The script backs up every database file — the console database, the per-client databases under clients/, and their write-ahead logs — to db_backups/backup_db_<timestamp>.zip, then clears the old build, extracts the new one and removes the update files. Your data, licence and settings are untouched. Finally, restart the app in Setup Node.js App.

Once you've confirmed an update is stable, delete older archives from db_backups/ — they count against your hosting quota.

Files you must protect

Inside your application root, treat these as crown jewels and keep your own offline copies:

• .env — contains your ENCRYPTION_KEY. Without it, every credential stored in the app is permanently undecryptable.
• Your recovery key — shown once, on screen, when you first sign in. It is never written to the server. Store it offline with the .env; it is the only way back into a locked-out account, because the app cannot send email.
• gws-backup.db — the console database: clients, encrypted credentials, schedules, the job log and the audit log.
• clients/ — one database per client, holding that client’s backup index. This is the bulk of your data and it is not optional: without it the console knows nothing about what has been backed up.
• gws-backup-archive.db — present on older installations only. If it is there, it counts.

Migrating servers? Stop the app first, then move the whole application folder and keep the same .env. Copy every database file together with its -wal and -shm companions — do not delete them and do not copy a .db on its own. The -wal holds committed data that has not been folded into the main file yet, so a database copied without it silently arrives missing its most recent minutes. Remember your licence key may only be live on one installation at a time — retire the old server when the new one goes live.

What we can and cannot do for you

What that means in practice:

• We will always try to help. Describe what you did, what you expected and what happened, paste any error text, and we will tell you what it means and what to try next. That help is free.
• cPanel varies more than you would think. Hosts ship different tools, different Node versions, different limits, and rename things. If your screen does not match this page, that is usually your host’s build rather than a mistake — tell us what you can see and we will map it.
• Some things only your host can do — installing a newer Node, opening outbound HTTPS, raising a memory or process limit, fixing a broken AutoSSL. We can tell you exactly what to ask for; we cannot ask for you.
• Nothing here reaches your backups. Support questions never require us to have your credentials, your encryption key or your data. If any instruction you receive appears to ask for those, it did not come from us.

Troubleshooting

• App won’t start / crash-log.txt mentions “node:sqlite” — your Node version is too old. GWS Backup uses the SQLite engine built into Node 22.5, so anything older cannot run it. On Setup Node.js App, pick 22.x or newer from the dropdown. On Application Manager there is no dropdown — the server has one system Node. Find it and check the version from the cPanel Terminal:
  ls -d /opt/cpanel/ea-nodejs*/bin/node /opt/alt/alt-nodejs*/root/usr/bin/node /usr/local/bin/node 2>/dev/null
  /opt/cpanel/ea-nodejs22/bin/node --version
  If the newest available is older than 22.5, your host has to install a newer Node — it is not something you or we can change from inside cPanel.
• "Failed to connect to the License Telemetry Server" — the server has no outbound internet access, or a firewall is blocking HTTPS.
• Google Drive connection redirects to the wrong address — NEXTAUTH_URL is missing or wrong (step 4).

Still stuck? Check the FAQ — it's searchable — or use the contact form (allow 1–2 days for free-edition support).