Get GWS Backup running securely on your cPanel server in about twenty minutes.
This guide covers cPanel and Linux servers. Running it somewhere else? There is a Docker install guide and a Windows install guide — both are shorter, and none of the steps below apply to either.
You'll need four things:
-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.The app itself needs roughly 100 MB of disk. Memory depends on how many backups run at the same time, not on how many workspaces you have: the console allows about 1 GB for each backup running at once, runs as many as the server’s memory allows, and queues the rest. Your actual backup data is stored in your destination (Google Drive, S3-compatible storage or Azure) — not on the web server.
Up to ten workspaces on a small server. On 2 GB of memory or less, backups run one at a time. Give each workspace its own start time, an hour or more apart (in the workspace’s Settings, under Schedule), so each one finishes before the next is due, and run each new workspace’s first full backup on its own: it takes far longer than the nightly backups that follow.
Never install GWS Backup inside public_html.
The application folder contains your encrypted credentials database and encryption keys. Those must never be web-accessible.
/home/youruser/gwsbackup ✓ correct
/home/youruser/public_html/backup ✗ never
Use a random subdomain name.
Give the installation an unguessable address — vault‑k7x93q.yourdomain.com rather than backup.yourdomain.com — and don't link to it from anywhere public.
Always use HTTPS. Run AutoSSL on the new subdomain before your first login. Sign-in only works over https://: on an http:// address the sign-in page says so, and signing in fails.
On shared cPanel hosting there is nothing here for you to do — your host runs the firewall and its defaults already allow what the application needs. This section is for a VPS or a dedicated server, where the rules are yours.
Inbound: 443 to the web server, and nothing else.
Node listens on a local port — 3000 by default — and must only be reachable through your web server, never directly from the internet.
Outbound needs Google’s APIs, our licence server, gwsbackup.com (the update check and update downloads) and whichever storage destination you have configured. The full list, with the reason for each entry, is on the requirements page.
If you filter outbound traffic by hostname, allow
googleusercontent.com as well as googleapis.com
— Drive serves the actual file content from there.
In cPanel → Domains → Create a New Domain (or Subdomains):
vault-k7x93q.yourdomain.compublic_html, e.g. /home/youruser/gwsbackup_webThen open SSL/TLS Status and run AutoSSL so the subdomain gets a certificate.
cPanel ships one of two tools for this — use whichever yours has. The settings are the same either way.
Whichever screen you are on, the values are:
gwsbackup (a folder in your home directory — not inside public_html)app.jsCreate or register the application, then stop it for now — there is nothing to run until the files are in place.
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 installer extracts the application and cleans up after itself. It also adds one cron job that keeps the console awake (see Keep it awake below). No terminal access? Use File Manager's Extract on the -app.zip instead, then delete the zip, and add the keep-awake cron job yourself (see Keep it awake).
Back in Setup Node.js App (Route A) or Application Manager (Route B), add an environment variable so Google Drive’s sign-in has the right address to come back to:
(your real subdomain, including https://).
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.
Visit https://your-random-subdomain/ in a browser:
The setup takes you through six steps, in order, and picks up at the right one if you sign out half way:
That's it. Each client’s schedule is in its own Settings, and Overview shows a short checklist of anything still to do.
There should not be any memory issues — these are precautions, not fixes. Five minutes now buys you an installation that looks after itself.
In Setup Node.js App or Application Manager, add an
environment variable alongside NEXTAUTH_URL:
That caps Node’s heap at 2 GB — use 1024 on a small VPS.
Restart the app after adding it.
Check with free -h. If the swap line reads zero, add a swap file:
On shared cPanel hosting this is your host’s department — skip it.
The installer does this one for you; just check it is there. cPanel starts the app only
when somebody opens a page, and its nightly maintenance restarts the web server, which
stops the app. Until somebody opens the console again, nothing runs: no scheduled
backups and no licence checks. So the installer adds one cron job that asks the console
for /api/health every five minutes, and leaves every other cron job alone.
In cPanel → Cron Jobs it ends in a comment starting
# gws-backup keep-awake. If the installer could not add it, it printed the
line for you to add yourself, on a five-minute schedule (*/5 * * * *), with
your own subdomain:
/api/health needs no sign-in and answers only {"ok":true}.
Updates are one command, and your database is backed up automatically first:
-app.zip and its matching -installer.php into your existing application root (the folder containing gws-backup.db).The script backs up all your databases to db_backups/ first, then swaps in the new build. Your data, licence and settings are untouched. Finally, restart the app.
Each night, housekeeping keeps the newest three archives in db_backups/ and removes older ones, so they do not eat your hosting quota. Move any you want to keep somewhere else.
From 1.00 you update this way once. After that the console says in the sidebar when a newer version is out, and an Admin installs it from Settings → System, under Updates, with Install update. It will not start while a backup or restore is running or waiting, and starts none while it works. It backs up your databases, installs the update and restarts. If the new version does not start, the one before it is put back by itself. Updating by hand, as above, always works too.
Inside your application root, treat these as crown jewels and keep your own offline copies:
.env — contains your ENCRYPTION_KEY. Without it, your encrypted backups and every credential stored in the app are permanently undecryptable..env. It resets that Admin account’s password, makes it
Admin again and unlocks it, and it is the way back in when nobody else can help,
because the app cannot send email. Other accounts are reset or unlocked by an Admin
under Settings → Users & security.gws-backup.db — the console database: clients, encrypted credentials,
schedules, the job log and the activity log.clients/ — one database per client, holding that client’s backup
index. This is the bulk of your data.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 — never a .db on its own.
And your key may only be live on one installation at a time — retire
the old server when the new one goes live.
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).