Skip to main content

Extending Backups to Your Home Directory with .backupinclude

  • Updated

The .backupinclude file gives you control over what additional files and directories are included in your site backups. By default, MODX Cloud backups contain:

  • All website files in the www/ directory
  • Database dump (.sql file)

If you need to preserve other files located in or below your home directory during backups, the .backupinclude file is exactly what you need.

Location

Create your .backupinclude file in your site's home directory:

/paas/[site-code]/home/.backupinclude

Format

The .backupinclude file is a simple text file with one path per line, relative to your home directory.

Basic Rules:

  • Each line should contain a single file or directory path
  • All paths are relative to your home directory
  • Lines starting with # are treated as comments
  • Empty lines are ignored
  • Include trailing slashes (/) for directories to ensure they're recognized as directories

Example

# This is a comment
  config.json
  custom_scripts/
  important_files/data.txt
  .hidden_folder/

Supported Patterns

The system recognizes explicit file and directory paths:

  • Individual files: myfile.txt
  • Directories: myfolder/ or myfolder

Note: Wildcards and other patterns are not currently supported.

Security Considerations

For security reasons, certain patterns will not be allowed:

  • Paths containing ../ (which would navigate outside your home directory)
  • Paths starting with / (absolute paths)

Any paths with these patterns will be ignored during the backup process.

How It Works

  1. During backup, the system reads your .backupinclude file
  2. All valid, existing paths are added to the backup
  3. The system automatically:
    • Verifies each path exists
    • Formats directory paths with trailing slashes
    • Prunes overlapping paths (if you specify both a directory and files within it, only the directory will be included)

The .backupinclude File Itself

The .backupinclude file itself can be included in your backup if you need to preserve your backup configuration.

Limitations

  • Files that have been excluded using standard exclusion patterns (like caches) cannot be re-included
  • Non-existent paths will be logged but ignored
  • Standard exclusions will still apply, including:
    • Web cache directories
    • Log files
    • Certain system files

Best Practices

  1. Keep your .backupinclude file minimal and focused on critical data
  2. Use comments to document why specific files are included
  3. Organize related files into directories when possible to simplify your include list
  4. Test your backup configuration after making changes
  5. Consider including configuration files and custom scripts that aren't part of your standard web files

Troubleshooting

If the files you specified aren't appearing in backups:

  • Confirm paths are relative to your home directory
  • Verify that the paths actually exist
  • Ensure paths don't contain ../ or start with /

Related articles