Install Guide

Before you start

You'll need four things:

• A cPanel account with the "Setup Node.js App" feature (CloudLinux Node.js Selector — most quality hosts have it).
• 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 ZIP — download GWS Backup v1.00. It contains the application payload (update.zip), the deploy script (update.php) and a README with these same instructions.
• 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.

2Create the Node.js application

cPanel → Software → Setup Node.js App → Create Application:

• Node.js version: 22.x or newer
• Application mode: Production
• Application root: gwsbackup (a folder in your home directory — not inside public_html)
• Application URL: the random subdomain from step 1
• Application startup file: app.js

Click Create, then Stop the app for now.

3Upload the application files

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

The wizard extracts the application and then deletes update.php and update.zip automatically to keep the server clean. No terminal access? Use File Manager's Extract on update.zip instead, then delete both update files manually.

4Set the application URL variable

Back in Setup Node.js App, add an environment variable so Google sign-in callbacks return to the right address:

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

5Start the app

Click Start (or Restart) in Setup Node.js App. On first boot the app generates its own encryption keys and writes them to .env and recovery-keys.txt inside the app folder.

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 update.zip and update.php into your existing application root (the folder containing gws-backup.db).
3. Run:

The script backs up your database to db_backups/backup_db_<timestamp>.zip, clears the old build, extracts the new one and removes the update files. Your database, 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.
• recovery-keys.txt — generated on first boot. Store it offline, then delete it from the server.
• gws-backup.db — the application database (client configs, encrypted credentials, backup index).

Migrating servers? Move the whole application folder, keep the same .env, and delete any -wal / -shm files before first start on the new machine. Remember your licence key may only be live on one installation at a time — retire the old server when the new one goes live.

Troubleshooting

• App won't start / crash-log.txt mentions "node:sqlite" — your Node version is too old; select Node 22+ in Setup Node.js App.
• "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).