=====================================================================
  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, Azure or local disk).

  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
---------------------------------------------------------------------

      docker compose pull
      docker compose up -d

  If you pinned GWSB_VERSION in .env, set it to the new version first.
  Pinning is recommended: it makes updating a decision you make rather
  than something that happens on the next restart.

  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.

  Cannot connect a Google Workspace / OAuth callback fails
      NEXTAUTH_URL is unset or wrong. It must be the address your
      browser actually reaches the console on, including https://.

  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
=====================================================================