Support & Documentation

Getting Started

Welcome to GWS Backup Support. This documentation will guide you through setting up your backup server and connecting your first Google Workspace client.

If you have questions about API limits, backup speeds, or "Stopped" statuses, please review our Frequently Asked Questions.

Support is free, and stays free for as long as we can manage it — on the free ten-workspace licence as much as on any other. Email support@gwsbackup.com and a person reads it. Early adopters get particular attention: if you took a chance on this before it had a track record, that earns you more of our time, not less.

If an update installed from the console fails, the console says so and an Admin can send us a report; it shows everything it sends first, and sends nothing without that click. We normally publish a fixed version within 48 hours, and it appears under Settings → System. Email us only if no fix has appeared by then, or the fix fails too.

Minimum specs & requirements

Read this before you start: two of the items below stop the application dead if they are missing, and it is much less annoying to find out now.

The two hard requirements

• Node.js 22.13 or newer, on cPanel. Not a preference — GWS Backup uses the SQLite engine built into Node, which works without a special switch only from 22.13, so it will not start on anything older. On cPanel this is whatever versions your host offers in Setup Node.js App; if the newest on offer is older than 22.13, the application cannot run there. The Windows installer and the Docker image bring their own.
• Your licence key. Setup stops at its Licence step until a valid key is entered, and checking a key needs an internet connection. Keys are free — ask for one on the home page. We will endeavour to send it automatically. If our system detects an issue with the details entered, we’ll contact you directly to confirm the submission, usually within 48 hours.

Server

• Memory: about 1 GB for each backup running at the same time, plus headroom for the application itself. It depends on how many backups run at once, not on how many workspaces you have: backups that don’t fit wait their turn. On a small server (2 GB or less) they run one at a time, so for up to ten workspaces give each its own start time, an hour or more apart (in its Settings, under Schedule), and run each first full backup on its own.
• CPU: 1–2 vCPU cores is enough for the engine and its parallel workers. Backups are limited by Google’s API rate limits far more than by your processor.
• Disk: about 100 MB for the application, and on cPanel as much again once the console has installed an update (it keeps the version before, to fall back to), plus room for its databases, which grow with the number of files you protect. Your actual backup data lives in your destination — Google Drive, S3-compatible storage or Azure, or a local folder on Windows — not on this server.
• Outbound HTTPS to Google’s APIs, our licence server and gwsbackup.com (for updates). No inbound ports need opening beyond the web server itself — the full list is under Network & firewall below.
• HTTPS on the console. Signing in only works over https://, or on the machine itself. Run AutoSSL (or your own certificate) on the subdomain before you sign in for the first time.

Network & firewall

GWS Backup needs a great deal of outbound access and almost no inbound. Getting that asymmetry right is most of what securing an installation amounts to.

Outbound — all of this has to be allowed

Inbound — keep it as small as you can

• The console’s own port, and nothing else. Restrict it to where you actually administer from — an office address, a VPN range — rather than to the whole internet.
• Hosted server: 443 to the web server only. Node listens on a local port (3000 by default) and Passenger or your proxy reaches it over loopback. If that port is reachable from outside, it bypasses your web server, your TLS and any address restriction you put there.
• Docker: publish only to the interface you need. If something else terminates TLS in front of it, publish as 127.0.0.1:3000:3000 so the container is not on the network at all.
• Windows: the installer creates the rule for you — inbound on the console’s port, private profile only — and removes it when you uninstall. Normally 3000; if that was taken at setup time the installer chose a free port and the rule follows it. You will never see Windows ask, because the application runs as SYSTEM in session 0 and cannot put a dialog on anyone’s desktop. Left to itself Windows silently blocks it, while loopback carries on working and hides the problem until another machine tries to connect. Another machine can open the console, but signing in from there needs https://.

What it never needs — do not open these

• Nothing inbound from Google. The application always initiates. Even the OAuth callback comes back through your browser, not from Google’s servers, so there is no rule to add for it.
• Nothing inbound from us. We never connect to your installation, for support or for anything else.
• No SMTP. The product sends no email at all, so there is no reset link. The recovery key it shows you at setup is how the Admin made at setup gets back in, after a lost password or a locked account; an Admin unlocks or resets everyone else.

PHP — for the installer

The application itself is Node.js and does not use PHP. PHP runs the installer, which backs up your databases, unpacks a release and adds the small job that keeps the app awake. Updates installed from the console run the same installer, so keep PHP available on the command line. Extracting the zip by hand in File Manager works without PHP, but skips the database backup and the keep-awake job.

• Any PHP 8.x with the ZipArchive extension enabled (standard on cPanel). The script deliberately avoids newer-only syntax, so it is not fussy about the minor version.
• If you get the choice, pick PHP 8.3: 8.1 is already end of life and 8.2 reaches it in December 2026.

Google Workspace side

• Super Admin access to the workspace you want to protect, to authorise domain-wide delegation.
• A Google Cloud service account with the required API scopes. Each client’s Connect page in the console gives you the exact scopes to paste — you do not need to work them out.

Installation

Three ways to run it: cPanel, Windows and Docker. Each has its own step-by-step guide.

cPanel / shared hosting

The easiest way to run GWS Backup round the clock without looking after a server. If your host offers cPanel with Setup Node.js App or Application Manager on Node.js 22.13 or newer, you can be up in about twenty minutes.

Two rules that matter more than any of the steps:

• Install outside public_html. The application folder holds your encrypted credentials database and the .env with your encryption key. Under the web root, one misconfiguration puts both within reach of anyone on the internet.
• Serve it on a randomly-named subdomain — something like vault-k7x93q.yourdomain.com, not backup.yourdomain.com. Bots scan the obvious names looking for admin panels.

In outline: create the subdomain and run AutoSSL, create the Node.js application pointing at app.js, upload the release zip and its matching installer to the application root, run the installer, set NEXTAUTH_URL to your full https:// address, then start the app and complete setup in the browser.

Unpacking is one line in cPanel’s Terminal (or over SSH), from the application root:

That script backs up your existing databases before it extracts anything, removes the zip and any older installers, and adds a small cron job that keeps the app awake. It stays in the folder for the next update. If your host gives you no terminal, use File Manager’s Extract on the release zip instead and delete the zip afterwards. That skips the database backup and the keep-awake job, so add the job by hand.

→ Follow the full step-by-step cPanel install guide

A Linux server without cPanel

Use Docker. The cPanel package will run under any process manager on Node.js 22.13 or newer, but there is no guide for it, and outside cPanel and Windows the console cannot install its own updates: it shows where to download them.

Docker

The image carries its own Node runtime, so there is nothing to install first and no version to check — two files, two generated secrets, and docker compose up -d. Your databases live in a Docker volume, so updating replaces the container and leaves them alone.

→ Follow the full step-by-step Docker install guide

Release notes

What each version changed — read the release notes. From 1.00 the download page offers only the current version.

Windows

One installer, no terminal work: it installs Node.js if the PC needs it, and registers GWS Backup to start with Windows before anyone signs in, so a machine that reboots overnight carries on backing up instead of waiting at the lock screen.

Windows 10, Windows 11 or Server 2016 and newer, 64-bit. The installer is not yet code-signed, so Windows will warn about an unrecognised publisher — the guide explains what to check instead.

→ Follow the full step-by-step Windows install guide