Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wimpysworld/gotosocial-backup
Comprehensive backup script for GotoSocial 🦥
https://github.com/wimpysworld/gotosocial-backup
activitypub backup gotosocial sqlite3
Last synced: about 2 months ago
JSON representation
Comprehensive backup script for GotoSocial 🦥
- Host: GitHub
- URL: https://github.com/wimpysworld/gotosocial-backup
- Owner: wimpysworld
- License: agpl-3.0
- Created: 2024-11-15T12:30:32.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2024-11-15T14:30:43.000Z (about 2 months ago)
- Last Synced: 2024-11-15T14:32:47.461Z (about 2 months ago)
- Topics: activitypub, backup, gotosocial, sqlite3
- Language: Shell
- Homepage:
- Size: 23.4 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# GoToSocial Backup
**A comprehensive backup script for [GoToSocial](https://gotosocial.org/) instances**
**Made with 💝 for 🦥**
# GoToSocial Backup
A comprehensive backup script for [GoToSocial](https://gotosocial.org/) instances that handles data export, SQLite database backup, and local media file backup with incremental storage using hard-links and optional encryption of sensitive data.
## Features
- Complete instance backup including:
- GoToSocial data export 🦥
- SQLite database backup with integrity checking ️🗃️
- Local media backup of attachments 📎 and custom emojis 🙂
- Incremental backups using hard-links to save space 🤏
- Backup structure that preserves directory hierarchy 📂
- Configurable retention period 📅
- Automatic log rotation ️♻️
- Support for both NixOS ️❄️ and traditional Linux distributions 🐧
- Optional encryption of sensitive data 🔐
- Optional failure notifications via [ntfy.sh](https://ntfy.sh) ️⚠️
- Suitable for sending backups to untrusted remote storage using [rsync](https://rsync.samba.org/) or [rclone](https://rclone.org/) 🚀
### Error Handling
The script includes comprehensive error checking:
- Verifies root access
- Checks for required tools
- Validates database accessibility
- Performs SQLite integrity checks
- Verifies backup completeness
### Caveats 🚨
- Designed to be run in the root context
- There is no support for PostgreSQL databases
- There is no built-in support for sending backups to remote locations
- Use `rsync`, `rclone` or similar tools to handle that
## Requirements
- Bash
- curl
- gzip
- SQLite3
- rsync
- OpenSSL
## Installation
1. Download the script:
```bash
curl -O https://raw.githubusercontent.com/wimpysworld/gotosocial-backup/gotosocial-backup.sh
```
2. Make it executable:
```bash
chmod 700 backup-gotosocial.sh
chown root:root backup-gotosocial.sh
```
## Configuration
The script can be configured by copying [gotosocial-backup.conf.example](https://raw.githubusercontent.com/wimpysworld/gotosocial-backup/gotosocial-backup.conf.example) `/etc/gotosocial-backup.conf` and editing the following variables accordingly:
```bash
# Root directory for backups
BACKUP_ROOT="/mnt/data/backup/gotosocial"
# Path to GoToSocial configuration file
GTS_CONFIG="/etc/gotosocial/config.yaml"
# Path to the GoToSocial SQLite database
GTS_DB="/var/lib/gotosocial/database.sqlite"
# Retention period in days
RETENTION_DAYS=28
# Encryption passphrase use to encrypt GtS exports and database
PASSPHRASE="mysupersecretpassphrase"
# Your ntfy instance
NTFY_SERVER="ntfy.sh"
# The topic you want to send gotosocial-backup failure alerts to
NTFY_TOPIC="mygotosocial-alerts"
```
## Distribution-specific Notes
### NixOS
On NixOS, the script automatically detects and uses the `gotosocial-admin` wrapper that is available at `/run/current-system/sw/bin/gotosocial-admin`. No additional configuration is needed.
### Traditional Linux Distributions
On traditional Linux distributions, the script requires the `gotosocial` binary to be in the system PATH and uses the specified configuration file path (`GTS_CONFIG`).
## Usage
### Manual Execution
Run the script as root:
```bash
sudo ./gotosocial-backup.sh
```
## Automated Backups
### Using Cron
Add to root's crontab for automated backups:
```bash
sudo crontab -e
```
Add a line for hourly backups:
```bash
0 * * * * /path/to/gotosocial-backup.sh
```
### Using systemd timer
For systems using systemd, you can create a timer unit to schedule backups.
This provides better logging and monitoring capabilities compared to cron.
1. Create the service unit file at `/etc/systemd/system/gotosocial-backup.service`:
```ini
[Unit]
Description=Backup GotoSocial database and local media
[Service]
ExecStart=/path/to/gotosocial-backup
User=root
```
2. Create the timer unit file at `/etc/systemd/system/gotosocial-backup.timer`:
```ini
[Unit]
Description=Run GotoSocial backup periodically
[Timer]
OnBootSec=5min
OnUnitActiveSec=4h
RandomizedDelaySec=300
[Install]
WantedBy=timers.target
```
Adjust the backup interval by changing `OnUnitActiveSec` to the desired duration.
3. Reload systemd to recognize new units
```bash
sudo systemctl daemon-reload
```
4. Enable timer to run at boot
```bash
sudo systemctl enable gotosocial-backup.timer
```
5. Start the timer
```bash
sudo systemctl start gotosocial-backup.timer
```
6. Verify the timer is active:
```bash
sudo systemctl status gotosocial-backup.timer
```
7. List all timers
```bash
sudo systemctl list-timers
```
8. Monitor backup execution:
```bash
sudo journalctl -u gotosocial-backup.service
```
9. Follow logs in real-time
```bash
sudo journalctl -u gotosocial-backup.service -f
```
The systemd timer configuration includes:
- Random delay of up to 5 minutes to prevent exact-hour execution
- Persistent timing to catch up on missed backups after system downtime
- Proper logging integration with journald
## Backup Structure
The script creates timestamped backup directories:
```
/mnt/data/backup/gotosocial/
├── 20241113_180102
│ ├── database.sqlite.gz.enc
│ ├── export.json.gz.enc
│ └── mnt
│ └── data
│ └── gotosocial
│ └── storage
│ ├── 01CCJ5GQF7A2KXVDPQ9Q9X23Q2
│ │ └── attachment
│ │ └── original
│ │ ├── 01JCF13JSSDJ0H8E9CWFFW2GVZ.png
│ │ └── 01JCF13K0R2HJDZWTPWGRNAPZ2.jpeg
│ ├── 01H7KYSZYN26CWTKT9JNKSZ2XB
│ │ ├── attachment
│ │ │ └── original
│ │ │ └── 01JCF1V56JDJ3SW03V82PFSQ37.png
│ │ └── emoji
│ │ └── original
│ │ └── 01JCJPE20Z1EYX3RTFBVTMM8JB.png
│ └── 01NATX9MGDJF8ESH0Q4TD5VAV7
│ └── attachment
│ └── original
│ ├── 01JCF2RK21FM491KRKSFTBFXWD.png
│ └── 01JCF2X4KN3032X5ZHRZ94H5MQ.png
├── backup.log
└── latest -> /mnt/data/backup/gotosocial/20241113_180102
```
Each backup includes:
- Compressed SQLite database backup (`database.sqlite.gz`) or encrypted (`database.sqlite.gz.enc`)
- Compressed GoToSocial export (`export.json.gz`) or encrypted (`export.json.gz.enc`)
- Local media files (attachments and emojis) with preserved directory structure
- A `latest` symlink pointing to the most recent successful backup
### Log File
The script maintains a log file at `$BACKUP_ROOT/backup.log`.
The log is automatically rotated to keep the most recent 4096 lines by default.
### Backup Retention
The script maintains backups according to these rules:
1. Keeps all backups from the current day
2. Keeps all backups newer than the retention period
3. Removes backups that are both:
- Older than the retention period
- Not created on the current day
# Restoring GoToSocial Backups
In this example:
- The backup root is: `/mnt/data/backup/gotosocial`
- The backup timestamp is: `20241115_122300`
- The database is: `/var/lib/gotosocial/database.sqlite`
- The storage is: `/var/lib/gotosocial/storage/`
1. Source the configuration file
This step is necessary to set the environment variables to aid the recovery process.
```bash
source /etc/gotosocial-backup.conf
```
2. Stop GoToSocial
```bash
sudo systemctl stop gotosocial
```
3. Decrypt database and export file (if encrypted)
```bash
openssl enc -d -aes-256-cbc -pbkdf2 -in database.sqlite.gz.enc -out database.sqlite.gz -pass pass:"${PASSPHRASE}"
openssl enc -d -aes-256-cbc -pbkdf2 -in export.json.gz.enc -out export.json.gz -pass pass:"${PASSPHRASE}"
```
4. Uncompress database and export files
```bash
gunzip database.sqlite.gz
gunzip export.json.gz
```
5. Preserve the existing database
```bash
mv /var/lib/gotosocial/database.sqlite /var/lib/gotosocial/database.sqlite.old
```
6. Restore the database
```bash
cp $BACKUP_ROOT/20241115_122300/database.sqlite /var/lib/gotosocial/database.sqlite
chown gotosocial:gotosocial /var/lib/gotosocial/database.sqlite
chmod 644 /var/lib/gotosocial/database.sqlite
```
7. Restore the export (*optional*)
If your SQLite backup is intact, there is no need to restore the export file.
However, if you need to restore the export file, you can do so using the following command:
```bash
gotosocial --config-path /etc/gotosocial/config.yaml admin import --path export.json
```
8. Preserve existing media
```bash
mv /var/lib/gotosocial/storage /var/lib/gotosocial/storage.old
```
9. Restore media files
```bash
rsync -av $BACKUP_ROOT/20241115_122300/var/lib/gotosocial/storage /var/lib/gotosocial/storage/
chown -R gotosocial:gotosocial /var/lib/gotosocial/storage
```
10. Start GoToSocial
```bash
systemctl start gotosocial
```
Verify everything is working as expected:
- Check logs for errors: `journalctl -u gotosocial`
- Verify web interface accessibility
- Test federation
## References
These are some references that helped me create this script:
- https://docs.gotosocial.org/en/latest/admin/backup_and_restore/
- https://litestream.io/alternatives/cron/