From 0b0950a32ca2953f02fa3e1ee1ef0bd5175cc95f Mon Sep 17 00:00:00 2001 From: DJ Mountney Date: Fri, 16 Jan 2026 17:11:41 -0800 Subject: [PATCH 1/2] feat: Include upgrade instructions --- .cursor/commands/update-changelog.md | 38 +++++++ docs/README.md | 1 + docs/index.md | 1 + docs/quickstart.md | 17 +++ docs/upgrading.md | 155 +++++++++++++++++++++++++++ on-prem/CHANGELOG.md | 34 +++++- on-prem/VERSION | 1 + on-prem/docker-compose.cache.yml | 4 +- on-prem/docker-compose.database.yml | 4 +- on-prem/docker-compose.full.yml | 4 +- on-prem/scripts/check-env.sh | 94 ++++++++++++++++ on-prem/scripts/generate-compose.sh | 12 ++- 12 files changed, 360 insertions(+), 5 deletions(-) create mode 100644 .cursor/commands/update-changelog.md create mode 100644 docs/upgrading.md create mode 100644 on-prem/VERSION create mode 100755 on-prem/scripts/check-env.sh diff --git a/.cursor/commands/update-changelog.md b/.cursor/commands/update-changelog.md new file mode 100644 index 0000000..cc276f2 --- /dev/null +++ b/.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 diff --git a/docs/README.md b/docs/README.md index 3edbd18..148861b 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 3fffc44..c2f6ccf 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/quickstart.md b/docs/quickstart.md index 5445085..f0dacc9 100644 --- a/docs/quickstart.md +++ b/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 + +# 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`: diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..6e049b2 --- /dev/null +++ b/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 + +# 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 + +# Regenerate compose file if needed +./scripts/generate-compose.sh + +# 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 + +# 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) +``` diff --git a/on-prem/CHANGELOG.md b/on-prem/CHANGELOG.md index 4bd14cb..2ec9626 100644 --- a/on-prem/CHANGELOG.md +++ b/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 + + diff --git a/on-prem/VERSION b/on-prem/VERSION new file mode 100644 index 0000000..dcd5906 --- /dev/null +++ b/on-prem/VERSION @@ -0,0 +1 @@ +staging diff --git a/on-prem/docker-compose.cache.yml b/on-prem/docker-compose.cache.yml index 7e48ddb..ee65d9e 100644 --- a/on-prem/docker-compose.cache.yml +++ b/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 diff --git a/on-prem/docker-compose.database.yml b/on-prem/docker-compose.database.yml index a46b70a..e6dc197 100644 --- a/on-prem/docker-compose.database.yml +++ b/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 diff --git a/on-prem/docker-compose.full.yml b/on-prem/docker-compose.full.yml index 865dbc9..e164787 100644 --- a/on-prem/docker-compose.full.yml +++ b/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 diff --git a/on-prem/scripts/check-env.sh b/on-prem/scripts/check-env.sh new file mode 100755 index 0000000..c0c5b57 --- /dev/null +++ b/on-prem/scripts/check-env.sh @@ -0,0 +1,94 @@ +#!/bin/bash +# +# Check for missing environment variables +# Compares .env against .env.example to find variables that may need to be added +# +# Usage: +# ./scripts/check-env.sh + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ON_PREM_DIR="$SCRIPT_DIR/.." + +ENV_FILE="$ON_PREM_DIR/.env" +EXAMPLE_FILE="$ON_PREM_DIR/.env.example" + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' + +if [ ! -f "$ENV_FILE" ]; then + echo -e "${RED}Error: .env file not found${NC}" + echo "Run ./scripts/setup.sh first to create your .env file" + exit 1 +fi + +if [ ! -f "$EXAMPLE_FILE" ]; then + echo -e "${RED}Error: .env.example file not found${NC}" + exit 1 +fi + +echo "Checking for missing environment variables..." +echo "" + +MISSING=() +COMMENTED=() + +while IFS= read -r line || [ -n "$line" ]; do + # Skip comments and empty lines + [[ "$line" =~ ^[[:space:]]*# ]] && continue + [[ -z "$line" ]] && continue + + # Extract variable name (handle lines with or without values) + var_name=$(echo "$line" | cut -d'=' -f1 | tr -d '[:space:]') + + # Skip if empty + [ -z "$var_name" ] && continue + + # Check if variable exists in .env (either set or commented) + if grep -q "^${var_name}=" "$ENV_FILE" 2>/dev/null; then + continue + elif grep -q "^#.*${var_name}=" "$ENV_FILE" 2>/dev/null; then + COMMENTED+=("$var_name") + else + MISSING+=("$var_name") + fi +done < "$EXAMPLE_FILE" + +if [ ${#MISSING[@]} -eq 0 ] && [ ${#COMMENTED[@]} -eq 0 ]; then + echo -e "${GREEN}All environment variables are present in .env${NC}" + exit 0 +fi + +if [ ${#MISSING[@]} -gt 0 ]; then + echo -e "${RED}Missing variables (not in .env):${NC}" + for var in "${MISSING[@]}"; do + echo " - $var" + done + echo "" + echo "To add missing variables, copy them from .env.example:" + echo " grep 'VARIABLE_NAME' .env.example >> .env" + echo "" + # Also show commented variables before exiting if any + if [ ${#COMMENTED[@]} -gt 0 ]; then + echo -e "${YELLOW}Commented variables (may need review):${NC}" + for var in "${COMMENTED[@]}"; do + echo " - $var" + done + echo "" + fi + exit 1 +fi + +if [ ${#COMMENTED[@]} -gt 0 ]; then + echo -e "${YELLOW}Commented variables (may need review):${NC}" + for var in "${COMMENTED[@]}"; do + echo " - $var" + done + echo "" +fi + +exit 0 diff --git a/on-prem/scripts/generate-compose.sh b/on-prem/scripts/generate-compose.sh index 0c46818..025e407 100755 --- a/on-prem/scripts/generate-compose.sh +++ b/on-prem/scripts/generate-compose.sh @@ -21,6 +21,14 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" TEMPLATES_DIR="$SCRIPT_DIR/../templates" OUTPUT_DIR="$SCRIPT_DIR/.." +# Read VERSION file +VERSION_FILE="$SCRIPT_DIR/../VERSION" +if [ -f "$VERSION_FILE" ]; then + VERSION=$(tr -d '[:space:]' < "$VERSION_FILE") +else + VERSION="unknown" +fi + # Determine how to run yq YQ_CMD="" if command -v yq &> /dev/null; then @@ -141,9 +149,11 @@ echo "Output: $OUTPUT_FILE" # Generate header with name field cat > "$OUTPUT_FILE" << EOF -# Generated by: ./scripts/generate-compose.sh +# Currents On-Prem Docker Compose +# Version: $VERSION # Profile: $PROFILE_NAME - $PROFILE_DESC # +# Generated by: ./scripts/generate-compose.sh # Includes Traefik for TLS termination (opt-in with: --profile tls) # Enable with: docker compose --profile tls up From d9836022e9a72bafba94c2c2537561611a0e316e Mon Sep 17 00:00:00 2001 From: DJ Mountney Date: Fri, 16 Jan 2026 17:15:40 -0800 Subject: [PATCH 2/2] chore: Add updated release instructions --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5ca43b7..e99cc97 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ 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 @@ -40,7 +40,7 @@ Releases are tied to Currents container image tags, which use date-based version 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" ```