Backups | Automad

Automad is a flat-file content management system and doesn't use a database. All content, settings and themes are stored as plain files in the installation directory, so a backup is simply a copy of those files. This page explains which files matter, how to back them up and how to automate version-controlled backups to GitHub.

What to Back Up

The easiest approach is backing up the complete installation directory, except for a few paths that are listed below. Such a backup is self-contained: it includes Automad itself together with your content and themes, so it can be restored from a single location or ZIP file without installing Automad first. A backup should contain the following directories and files:

Path	Content
`automad`, `lib`, `vendor`, `index.php`	Automad itself and its dependencies.
`.htaccess`	The server configuration for Apache and LiteSpeed. Note that this file is hidden on macOS and Linux.
`pages`	All pages, including their content, drafts and attached files.
`shared`	The global data and files, as well as the components.
`packages`, `composer.json`, `composer.lock`	The installed themes and extensions.

The cache directory doesn't need to be backed up, since its content is generated again automatically. The same applies to deleted pages in pages/.trash. The config directory is left out on purpose. It contains the user accounts and credentials such as the mail password and API keys, which should never end up in a backup for security reasons.

Version-Controlled Backups

Since everything is stored in files, a site can be tracked with Git just like source code. Every backup then becomes a commit, and you can go back to any earlier state of your site, compare changes over time and restore single pages. Hosting the repository on GitHub also keeps a copy of your site outside of your server.

GitHub Backup Action

The Automad GitHub Backup Action automates this process. It is a GitHub workflow that runs on a schedule, connects to your server via SSH, synchronizes your entire installation with the repository using rsync and commits all changes. Once it is set up, no further work is required.

GitHub Backup Action

In order to use the action, your hosting must support SSH access with key-based authentication. You also need an SSH key pair, which you can generate with ssh-keygen on any Unix-like machine. The public key has to be installed on your host, so that the action can connect to it.

Create a new private repository on GitHub that will hold the backup.
Add a workflow file to the repository, for example .github/workflows/backup.yml, with the content shown below.
Add the secrets and variables that are referenced in the workflow in the repository settings under Secrets and variables → Actions.
Run the workflow once manually from the Actions tab in order to test the setup. The repository now contains a copy of your site.

The following workflow runs every Sunday at 4:00 AM. It can also be started manually at any time.

name: GitHub Backup

on:
  schedule:
    - cron: "0 4 * * 0"
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Backup Action
        uses: automadcms/automad-github-backup-action@master
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ssh_key_private: ${{ secrets.SSH_KEY_PRIVATE }}
          ssh_key_public: ${{ secrets.SSH_KEY_PUBLIC }}
          ssh_user: ${{ secrets.SSH_USER }}
          ssh_host: ${{ vars.SSH_HOST }}
          docroot: ${{ vars.DOCROOT }}
          branch: master

The workflow expects the following secrets and variables. Note that GITHUB_TOKEN is provided by GitHub automatically and doesn't have to be created.

Name	Type	Description
`SSH_KEY_PRIVATE`	Secret	The private SSH key that is used to access the host.
`SSH_KEY_PUBLIC`	Secret	The matching public key.
`SSH_USER`	Secret	The SSH username.
`SSH_HOST`	Variable	The server where Automad is installed.
`DOCROOT`	Variable	The path to the Automad installation on the server.

You can change the schedule by editing the cron expression in the workflow file. Note that GitHub runs scheduled workflows in UTC. Use the branch option in case the backup should be committed to another branch than master.

What Is Included

The action copies the complete installation, including Automad itself, your content, the installed packages and the .htaccess file. Only the following paths are excluded:

Path	Reason
`config`	Contains the user accounts and credentials, which must never end up in a repository.
`cache`	Is generated again automatically.
`pages/.trash`	Contains deleted pages.
`sitemap.xml`	Is generated again automatically.
`bin`, `README.md`, `.git`, `.github`, `.gitignore`, `.editorconfig`, `.history`	Development, editor and Git files that are not part of the site.

Files that are deleted on the server are also removed from the repository on the next run, while older versions remain available in the Git history. In addition, the action commits a small .github/keep-alive file once a month, so that GitHub doesn't disable the scheduled workflow due to inactivity.

Restoring a Backup

Since a backup contains a complete installation, restoring it only requires copying or extracting the files into the document root, for example using SFTP or rsync. Make sure that hidden files like .htaccess are included and that PHP has write permissions for all files and directories. When restoring to a new server, Automad starts with the default configuration and asks you to create a new user account. Settings such as the email configuration then have to be set up again.