How to update GoBlogger

Update strategy in one line: back up, compare, test, then go live.

Recommended workflow

1. Create a backup of:

   • custom/ (your CSS, template, and locale customizations)
   • content/ (your posts and pages)
   • .env (configuration)
   • credentials file

   Note: You do not need to back up theme/ — it's part of the release and should be overwritten with the new version.

2. Build and run the new version in a test environment:

   • local build: make build
   • release archives: make release (all platforms) or make release-linux (Linux only)

3. Review relevant diffs:

   • read the release notes for the new version
   • check the CHANGELOG.md for details on new features, fixes, and breaking
   • template changes
   • new or removed environment variables
   • changes in index or routing behavior

4. Check your custom files for compatibility:

   • If you have custom templates in custom/templates/, review if they reference fields or structures that changed
   • If you have custom locales in custom/locales/, verify new translation keys exist
   • If data structures changed, old custom files could break the installation or display incorrectly

5. Run a smoke test (/, /tags/..., /search-index.json, /tag-index.json, admin):

   • include /search?q=test for current versions with server-side search

6. Deploy to production.

Why custom/ and theme/ are handled differently

theme/ is part of the release package and should be replaced with each update:

• Contains new features, bug fixes, and improvements
• Safely replaced by running the new release
• Your customizations in custom/ are never affected

custom/ holds your CSS, template overrides, and locale customizations with a cascading override system:

• Never modified by updates — your customizations always survive
• No merge conflicts — updates to theme/ don't touch custom/
• Backup needed — if you lose custom/, you lose your customizations
• ⚠️ Compatibility risk — if internal structures or template fields change, custom templates or locale files may break the installation. Test after updates.

See Customising GoBlogger for details on the override system.

Rollback plan

Have rollback defined before updating: previous binary plus saved configuration, then restart the service.

This turns updates from risky into controlled operations.