A containerized version of Got Your Back to make it easy to back up your Gmail account. Can run standalone or as full/incremental cron jobs (default).

This is a multi-platform image which supports linux/amd64 and linux/arm64. linux/arm/v7 support is deprecated due to the upstream LSIO images deprecating armhf support.

Tags correspond with Got Your Back releases. :latest refers to the latest published release and all releases since 1.40 are available as individual tags (e.g. awbn/gyb:1.40 contains GYB v1.40).

GYB requires some bootstrapping to create a new project before you can run. For complete bootstrapping steps, see the GYB Wiki.

docker run -it -e [email protected] -e NOCRON=1 -v ${PWD}/config:/config awbn/gyb /app/gyb --action create-project

...and follow the prompts. See Bootstrapping Notes below for an abbreviated set of steps.

Once you've created the project and cached the credentials, you can run the container to start the background cron jobs. Make sure that you mount the same volume so that the credentials are re-used.

The first full backup will (likely) take a long time. It's recommend to do this as a one-off run:

docker run -it -e [email protected] -e NOCRON=1 -v ${PWD}/config:/config awbn/gyb /app/gyb --action backup

By default you should start the container in detached mode and let it run incremental and full backups. See the docker-compose or CLI examples below.

version: "3"
services:
  got-your-back:
    image: awbn/gyb
    container_name: got-your-back
    environment:
      - PUID=1000
      - PGID=1000
      - [email protected]
      - TZ=America/Los_Angeles
    volumes:
      - <path to data>:/config
    restart: unless-stopped

docker run -d \
  --name=got-your-back \
  -e PUID=1000 \
  -e PGID=1000 \
  -e [email protected] \
  -e TZ=America/Los_Angeles \
  -v <path to data>:/config \
  --restart unless-stopped \
  awbn/gyb

See GYB's wiki for information on how to restore from a backup. Running the command in a container might look like:

docker run -it -e [email protected] -e NOCRON=1 -v ${PWD}/config:/config awbn/gyb /app/gyb --action restore

Note that you must have given the OAuth token 'write' permissions to your gmail account during bootstrapping for restore to work. If you didn't, you can delete the <email>.cfg file from the /config volume to force GYB to prompt for a new token.

This container is based on LinuxServer.io's Alpine base image. This means you can take advantage of all the LSIO goodness, including regular base image updates, user/group identification, loading environment variables from files (docker secrets), etc. See the LSIO docs for more info.

This container can be configured to send you an email if your cron job(s) fail. To do so, you'll need to pass in the MAIL_TO, MAIL_FROM, SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, and, optionally, the SMTP_TLS env variables.

By default the container has two jobs which are run on a regular schedule. The 'Full' job runs at 1am every Sunday (timezone depends on the container's TZ) and does a full backup. The incremental job runs at 1am Monday-Saturday and does a partial backup using GYB's --search parameter. You can customize the timing of these jobs and the GYB command which is run using environment variables. You can also define your own custom job as well.

To run the full job at a different schedule, set the JOB_FULL_CRON env variable to valid cron syntax. To run a different command for that job (e.g., to include only a particular label), set the JOB_FULL_CMD env variable to /app/gyb <valid gyb command>. See the GYB Wiki for more info on valid GYB commands.

In addition to the JOB_FULL_ job, there are also the JOB_INC_ and JOB_EXTRA_ jobs. By default, the extra job is not used, but could be used to, e.g., back up a particular label more often. See the Parameters section for more details.

By default the container creates all new files in /config with a umask of 077 (rw for the owner, no permissions for group/others). This is because sensitive files containing auth tokens, etc will get created. However, this can cause issues if you swap users or if you access the files outside of the container. If you want the files created to be more widely accessible, you can pass a different umask (e.g., 022: rw for owner r for everyone else, or 100: rw for everyone) via the UMASK environment variable. Make sure you understand how umask works before relying on this for security.

See the GYB Wiki for authoritative steps. These are some rough notes:

• Run docker run -it -e [email protected] -e NOCRON=1 -v ${PWD}/config:/config awbn/gyb /app/gyb --action create-project and open the URL provided in the console
• Give access to GAM and paste the token into console
• Open the URL provided
• Configure the OAuth consent screen:
  • 'External' (if you're not using a gmail account that's part of a workspace)
  • 'App Name': GYB Docker (or whatever you want)
  • 'Support Email' and 'Developer Contact': your contact email
  • 'Scopes': none
  • 'Test users': Email addresses of the users you want to backup
• In the Google cloud console, click 'Credentials' -> 'Create Credential' -> 'OAuth client ID':
  • 'Application Type': Desktop App
  • 'Name': GYB (or anything)
• Run docker run -it -e [email protected] -e NOCRON=1 -v ${PWD}/config:/config awbn/gyb /app/gyb --action estimate --search "newer_than:7d"
  • Select Scopes (Recommended: 1,6 for read-only backups; Gmail read-only and storage quota)
  • Visit provided URL and paste token into the console
    • Google may warn you that the app is not verified; this is the app that you created in the step above (to verify: click the name of the app and check that the email matches what you entered as the developer email above). You're giving yourself permissions to your own data
  • At this point the credentials should be fully saved and the service account authorized
    • Note: If you are using an 'external' app with a status of 'testing' the tokens expire every seven days and need to be manually refereshed. See this issue and Google's documentation

# e.g. docker build -t awbn/gyb .
docker build -t <repo>[:<tag>] .

Multi-platform image:

# e.g. ./buildx.sh -t awbn/gyb 
./buildx.sh -t <repo>[:<tag>]

Uses container-structure-test. Will download the binary if it's not already on the path. Note that this does NOT extensively test GYB (other than ensuring the script can launch); it tests the container wrappers and functionality.

# e.g. ./test.sh awbn/gyb
./test.sh <repo>[:<tag>]

release.sh is a helper script for [re]publishing docker images against GYB releases using remote GitHub workflows. Useful if the code in the repo changes and you want to publish an updated docker image against a GYB release. Uses the GitHub cli. Note: must have contributor access to awbn/docker-gyb.

# e.g. ./release.sh v1.42 v1.50
./release.sh <tag...>