feat: Include upgrade instructions [CSR-3558]

.cursor/commands/update-changelog.md

@@ -0,0 +1,38 @@
+# Update Changelog
+
+Update the `[Unreleased]` section of the CHANGELOG based on commits since the last release.
+
+## Instructions
+
+1. **Find the latest git tag** by running:
+   ```bash
+   git describe --tags --abbrev=0
+   ```
+
+2. **Get commits between the latest tag and main** using the GitHub MCP tool:
+   - Use `list_commits` with the repository `currents-dev/docker`
+   - Compare from the latest tag to `main` branch
+   - Get the commit messages and descriptions
+
+3. **Categorize the commits** into the following sections based on their content:
+   - **Breaking Changes** — Changes that require user action or break backward compatibility
+   - **Compose File Changes** — Changes to templates or compose generation that require regeneration
+   - **New Environment Variables** — New variables added to `.env.example`
+   - **Changed Environment Variables** — Variables with changed defaults or behavior
+   - **Added** — New features
+   - **Changed** — Changes to existing features
+   - **Fixed** — Bug fixes
+   - **Removed** — Removed features
+
+4. **Update the CHANGELOG** at `on-prem/CHANGELOG.md`:
+   - Add entries under the `## [Unreleased]` section
+   - Follow the existing format and style
+   - Only include sections that have entries (skip empty sections)
+   - Do not duplicate entries that are already in the changelog
+
+## Notes
+
+- Skip merge commits and automated commits
+- Write clear, user-facing descriptions (not raw commit messages)
+- Group related commits into single entries where appropriate
+- Focus on what changed from the user's perspective

README.md

@@ -32,15 +32,15 @@ Releases are tied to Currents container image tags, which use date-based version
 
 ### Release Process
 
-1. **Update the image tag** in `on-prem/.env.example`:
+1. **Update the version** in `on-prem/VERSION` and the image tag in `on-prem/.env.example`:
 
 2. **Update the changelog** in `on-prem/CHANGELOG.md`:
    - Move items from "Unreleased" to a new version section
    - Add release date and summary of changes
 
 3. **Commit the release**:
    ```bash
-   git add on-prem/.env.example on-prem/CHANGELOG.md
+   git add on-prem/VERSION on-prem/.env.example on-prem/CHANGELOG.md
    git commit -m "release: on-prem 2026-01-14-001"
    ```
 

docs/README.md

@@ -11,6 +11,7 @@ The Docker Compose configuration is modular, allowing you to choose which data s
 - [🚀 Quickstart Guide](./quickstart.md)
 - [Container Image Access](./container-images.md)
 - [Configuration Reference](./configuration.md)
+- [Upgrading Currents On-Prem](./upgrading.md)
 - [Support Policy](./support.md)
 
 ## Additional Resources

docs/index.md

@@ -10,6 +10,7 @@ Docker Compose configuration for self-hosted Currents deployment.
 
 - [Quickstart Guide](quickstart.md) — Get up and running with Docker Compose
 - [Configuration Reference](configuration.md) — All environment variables and settings
+- [Upgrading Currents On-Prem](upgrading.md) — Upgrade workflows and version management
 - [Support Policy](support.md) — What's supported and maintenance responsibilities
 
 ## Quick Setup

docs/quickstart.md

@@ -266,6 +266,23 @@ docker compose logs mongodb
 
 The replica set initialization runs automatically on first start.
 
+If you see connection errors in service logs (e.g., "connection refused", "ECONNREFUSED", database connection failures), this is often due to timing issues with dependencies starting. Try restarting the service that's logging the error:
+
+```bash
+# Restart the specific service
+docker compose restart <service-name>
+
+# Or restart all services
+docker compose restart
+```
+
+For example, if the `api` service shows MongoDB connection errors, restart it:
+```bash
+docker compose restart api
+```
+
+The service will retry connecting to its dependencies once they're fully ready.
+
 ### Port Conflicts
 
 If ports are already in use, customize them in `.env`:

docs/upgrading.md

@@ -0,0 +1,155 @@
+# Upgrading Currents On-Prem
+
+This guide covers upgrading your Currents on-prem deployment to a new version.
+
+## Before You Begin
+
+1. Check the [CHANGELOG](https://github.com/currents-dev/docker/blob/main/on-prem/CHANGELOG.md) for the version you're upgrading to
+2. Review any breaking changes or required configuration updates
+3. Back up your data (see [Backup and Restore](./backup-restore.md))
+
+## Upgrade Types
+
+### Image-Only Updates
+
+When a new version only includes updated container images (no compose or config changes):
+
+```bash
+cd on-prem
+
+# Pull latest images
+docker compose pull
+
+# Restart with new images
+docker compose up -d
+```
+
+### Updates with Compose File Changes
+
+When the CHANGELOG indicates compose file changes:
+
+```bash
+cd on-prem
+
+# Stop services (recommended for major updates)
+docker compose down
+
+# Pull latest repository changes
+git pull
+
+# Regenerate your compose file (if using custom profile)
+./scripts/generate-compose.sh <your-profile>
+
+# Or if using a pre-generated profile, it's already updated by git pull
+
+# Pull new images
+docker compose pull
+
+# Start services
+docker compose up -d
+```
+
+### Updates with New Environment Variables
+
+When the CHANGELOG indicates new environment variables:
+
+```bash
+cd on-prem
+
+# Pull latest repository changes
+git pull
+
+# Check for missing variables
+./scripts/check-env.sh
+
+# Add any missing variables to your .env file
+# The script will show which variables are missing
+
+# Then follow the appropriate upgrade steps above
+```
+
+## Version Checking
+
+Check your current version:
+
+```bash
+# View the VERSION file
+cat on-prem/VERSION
+
+# Or check the header in your compose file
+head -5 on-prem/docker-compose.yml
+```
+
+Check running container versions:
+
+```bash
+docker compose ps --format "table {{.Name}}\t{{.Image}}"
+```
+
+## Rollback
+
+If you need to rollback to a previous version:
+
+```bash
+cd on-prem
+
+# Stop services
+docker compose down
+
+# Checkout the previous version
+git checkout <previous-tag-or-commit>
+
+# Regenerate compose file if needed
+./scripts/generate-compose.sh <your-profile>
+
+# Start services
+docker compose up -d
+```
+
+## Troubleshooting
+
+### Services won't start after upgrade
+
+1. Check logs for errors: `docker compose logs --tail=50`
+2. Verify all required environment variables are set: `./scripts/check-env.sh`
+3. Ensure compose file was regenerated if templates changed
+
+### Connection errors in logs
+
+If you see connection errors in service logs (e.g., "connection refused", "ECONNREFUSED", database connection failures), this is often due to timing issues with dependencies starting. Try restarting the service that's logging the error:
+
+```bash
+# Restart the specific service
+docker compose restart <service-name>
+
+# Or restart all services
+docker compose restart
+```
+
+For example, if the `api` service shows MongoDB connection errors, restart it:
+```bash
+docker compose restart api
+```
+
+The service will retry connecting to its dependencies once they're fully ready.
+
+### Database migration issues
+
+Some upgrades may require database migrations. The scheduler service runs migrations automatically on startup. Check scheduler logs:
+
+```bash
+docker compose logs scheduler
+```
+
+### Missing environment variables
+
+If services fail with missing configuration errors:
+
+```bash
+# Check what variables are missing
+./scripts/check-env.sh
+
+# Compare your .env with .env.example for new required variables
+diff <(grep -v '^#' .env | grep '=' | cut -d'=' -f1 | sort) \
+     <(grep -v '^#' .env.example | grep '=' | cut -d'=' -f1 | sort)
+```

on-prem/CHANGELOG.md

@@ -2,9 +2,41 @@
 
 All notable changes to the Currents on-prem Docker Compose deployment will be documented in this file.
 
-## Unreleased
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Added
 - Initial public release
 - Docker Compose configuration with modular profiles (full, database, cache)
 - Optional Traefik TLS termination
 - Documentation for quickstart, configuration, and container image access
+
+<!-- Template for future releases:
+
+## [YYYY-MM-DD-NNN]
+
+### Breaking Changes
+- List any breaking changes that require user action
+
+### Compose File Changes
+- Changes requiring `./scripts/sync-templates.sh` or `./scripts/generate-compose.sh`
+
+### New Environment Variables
+- New variables added to `.env.example`
+
+### Changed Environment Variables
+- Variables with changed defaults or behavior
+
+### Added
+- New features
+
+### Changed
+- Changes to existing features
+
+### Fixed
+- Bug fixes
+
+### Removed
+- Removed features
+-->

on-prem/VERSION

@@ -0,0 +1 @@
+staging

on-prem/docker-compose.cache.yml

@@ -1,6 +1,8 @@
-# Generated by: ./scripts/generate-compose.sh
+# Currents On-Prem Docker Compose
+# Version: staging
 # Profile: cache - Cache (redis)
 #
+# Generated by: ./scripts/generate-compose.sh
 # Includes Traefik for TLS termination (opt-in with: --profile tls)
 # Enable with: docker compose --profile tls up
 

on-prem/docker-compose.database.yml

@@ -1,6 +1,8 @@
-# Generated by: ./scripts/generate-compose.sh
+# Currents On-Prem Docker Compose
+# Version: staging
 # Profile: database - Database services (redis, mongodb, clickhouse)
 #
+# Generated by: ./scripts/generate-compose.sh
 # Includes Traefik for TLS termination (opt-in with: --profile tls)
 # Enable with: docker compose --profile tls up
 

on-prem/docker-compose.full.yml

@@ -1,6 +1,8 @@
-# Generated by: ./scripts/generate-compose.sh
+# Currents On-Prem Docker Compose
+# Version: staging
 # Profile: full - All services (redis, mongodb, clickhouse, rustfs)
 #
+# Generated by: ./scripts/generate-compose.sh
 # Includes Traefik for TLS termination (opt-in with: --profile tls)
 # Enable with: docker compose --profile tls up