Filesystem Mirror

Meerkat stores comments in the database and keeps a filesystem copy under content/comments by default. Use the mirror for Git history, backups, and database recovery.

#Configuring the mirror

Configure the mirror through .env:

1MEERKAT_MIRROR_ENABLED=true
2MEERKAT_MIRROR_PATH=/absolute/path/to/content/comments

MEERKAT_MIRROR_PATH is optional. Without it, Meerkat writes to content/comments in the project root.

Or use config/meerkat.php:

1'mirror' => [
2    'enabled' => true,
3    'path' => null,
4],

The application must be able to write to the path. Run php artisan meerkat:health to check it.

#Files saved to disk

Each thread has a directory. Root comments sit directly inside it, and replies are nested beneath their parent:

 1content/comments/
 2└── 2ed01b5f-355d-4a22-a3d5-d964cde4209f/
 3    ├── .meta
 4    └── 1779039555/
 5        ├── comment.md
 6        ├── .revisions
 7        └── replies/
 8            └── 1779039592/
 9                ├── comment.md
10                └── .revisions

Meerkat writes:

• comment.md for the comment front matter and Markdown body.
• .meta for thread-level state.
• .revisions for revision metadata when revisions are enabled.

#Rebuilding from the mirror

Import the default mirror, choose another source, or preview the import:

1php artisan meerkat:sync
2php artisan meerkat:sync --path=/srv/backup/meerkat/comments
3php artisan meerkat:sync --dry-run

The command creates or updates comments and threads and is safe to run more than once.

Meerkat reports invalid files, continues the import, and returns a failure exit code when errors occur.

#Deleted comments and threads

Thread state lives in .meta. A thread with trashed: true imports as soft-deleted. Change the value and run meerkat:sync again to restore it.

Comment state lives in comment.md:

• trashed: true imports the comment as soft-deleted.
• is_deleted: true imports it as a moderation tombstone.

#Limitations

Synchronization restores current comment content and moderation state, but not revision or moderation audit history.

#Keeping the mirror current

Normal Meerkat operations update the mirror. Direct database changes do not. Modify comments through Meerkat whenever possible.