=====================================================================
  GWS BACKUP — Docker
  by KIKO Solutions — https://gwsbackup.com
=====================================================================

Two files, three commands, and one thing you must not lose.

Full guide:  https://gwsbackup.com/download.html
Questions:   support@gwsbackup.com


---------------------------------------------------------------------
 1. WHAT YOU NEED
---------------------------------------------------------------------

  * Docker with the Compose plugin (Docker Desktop, or docker +
    docker-compose on Linux).
  * Your free licence key. The console stays on the activation screen
    until a valid key is entered. Request one at
    https://gwsbackup.com/contact.html?topic=licence-key
  * Outbound HTTPS, so the app can reach Google's APIs and the licence
    server.

  You do NOT need Node.js installed. The image carries its own.


---------------------------------------------------------------------
 2. INSTALL
---------------------------------------------------------------------

  Put the compose file and the env example in an empty directory,
  renaming them without the version prefix:

      mv gwsbackup-docker-<version>-compose.yml   docker-compose.yml
      mv gwsbackup-docker-<version>-env.example   .env.example

  Copy the example and fill in the two secrets:

      cp .env.example .env

  Generate them:

      openssl rand -hex 32      <- ENCRYPTION_KEY
      openssl rand -base64 32   <- NEXTAUTH_SECRET

  Then start it:

      docker compose up -d

  Open http://localhost:3000 (or whichever port you set), create your
  administrator account, SAVE THE RECOVERY KEY it shows you, and paste
  in your licence key.


---------------------------------------------------------------------
 3. THE ONE THING YOU MUST NOT LOSE
---------------------------------------------------------------------

  ENCRYPTION_KEY decrypts every stored client credential — service
  accounts, Drive OAuth tokens, S3 and Azure secrets.

  If you lose it, those credentials cannot be recovered by any means,
  by us or by anyone. Every client connection would have to be set up
  from scratch.

  Keep .env somewhere safe and separate from the server. Never change
  ENCRYPTION_KEY on an install that already holds data.

  The container refuses to start rather than quietly generating a new
  key, so a mistake here shows up as a container that will not boot,
  not as silent data loss. That refusal is the software protecting
  you — read what it says rather than working around it.


---------------------------------------------------------------------
 4. WHERE YOUR DATA LIVES
---------------------------------------------------------------------

  In a Docker named volume, not inside the container:

      /app/data/gws-backup.db          the console database
      /app/data/gws-backup-archive.db  frozen index of retired destinations
      /app/data/clients/<id>.db        one index per client workspace

  This is why an update does not touch your data. The container is
  replaced; the volume is not.

  Your BACKUPS are not here at all — they go to the destination you
  configure (Google Drive, S3-compatible storage or Azure; a local folder
  is offered only in the Windows edition).

  To back up the databases themselves:

      docker compose stop
      docker run --rm -v <project>_gwsbackup-data:/data -v "$PWD:/out" \
        alpine tar czf /out/gwsbackup-data.tar.gz -C /data .
      docker compose start

  Stopping first is not optional — copying a live SQLite database can
  produce a file that will not open.


---------------------------------------------------------------------
 5. UPDATING
---------------------------------------------------------------------

  Set GWSB_VERSION in .env to the new version, then:

      docker compose pull
      docker compose up -d

  The console tells you when a new version is out (Settings -> System,
  under Updates) and gives these steps with the version filled in.

  A compose file downloaded before 1.00 names its version on its image:
  line and ignores GWSB_VERSION. For the move to 1.00, change the number
  at the end of that line to 1.00 (or use the 1.00 compose file); from
  then on GWSB_VERSION in .env is all you change.

  Your databases, licence and settings are untouched.


---------------------------------------------------------------------
 6. COMMON PROBLEMS
---------------------------------------------------------------------

  "REFUSING TO START — Missing required environment"
      .env is absent or the secrets are blank. See section 2.

  "REFUSING TO START — ENCRYPTION_KEY is missing, but this install
  has a database that already holds data"
      The key that created this data is not being supplied. Restore
      the original .env. Do NOT generate a new key unless you accept
      losing every stored credential.

  SQLITE_READONLY, or permission errors on /app/data
      You have replaced the named volume with a host bind mount. The
      container runs as uid 1000; chown the directory to match, or go
      back to the named volume.

  Connecting a Google Drive destination fails, or Google's sign-in
  never comes back
      The OAuth app you made in Google Cloud must list the redirect
      address shown on Settings -> Destination. Behind a proxy that is
      the https:// address. Set NEXTAUTH_URL to that same address.

  Signing in fails from another machine
      Sign-in needs https://, except on the machine itself
      (http://localhost:3000). Put a reverse proxy with TLS in front
      and set NEXTAUTH_URL to its https:// address.

  "This account is locked after too many wrong tries"
      After 5 wrong passwords or two-step codes in a row, each try
      waits: 1 minute up to the 10th, 5 minutes up to the 15th,
      15 minutes up to the 20th. The 20th locks the account. The
      Admin made at setup unlocks it with the recovery key
      ("Forgotten your password?" on the sign-in page). Anyone else:
      an Admin unlocks them, or sets a new password, under
      Settings -> Users & security.

  Container is "unhealthy"
      docker compose logs will say why. The health check simply asks
      the console for its login page.


=====================================================================
  Support is free, and stays free for as long as we can manage it.
  support@gwsbackup.com
=====================================================================