diff --git a/README.md b/README.md index 6422b30..23c0baf 100644 --- a/README.md +++ b/README.md @@ -14,4 +14,45 @@ docker compose up -d ## Development -- [On-Prem Development Guide](on-prem/README.md) — Architecture, scripts, and release steps +- [On-Prem Development Guide](on-prem/README.md) — Architecture, scripts, and contribution guidelines + +## Releasing (On-Prem) + +Releases are tied to Currents container image tags, which use date-based versioning: `YYYY-MM-DD-NNN`. + +### Release Process + +1. **Update 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 commit -m "release: on-prem 2026-01-14-001" + ``` + +4. **Create a git tag** (namespaced for on-prem): + ```bash + git tag on-prem/2026-01-14-001 + ``` + +5. **Push**: + ```bash + git push && git push --tags + ``` + +### Tag Format + +Tags are namespaced by tool to allow for future additions: + +| Tool | Tag Format | Example | +|------|------------|---------| +| On-Prem | `on-prem/YYYY-MM-DD-NNN` | `on-prem/2026-01-14-001` | + +List all on-prem releases: +```bash +git tag -l 'on-prem/*' +``` diff --git a/on-prem/.env.example b/on-prem/.env.example index 0f5e38e..8db0054 100644 --- a/on-prem/.env.example +++ b/on-prem/.env.example @@ -51,6 +51,10 @@ GITLAB_STATE_SECRET= # Frequently Used Configuration # ============================================================================= +# Currents application images +DC_CURRENTS_IMAGE_REPOSITORY=513558712013.dkr.ecr.us-east-1.amazonaws.com/currents/on-prem/ +DC_CURRENTS_IMAGE_TAG=staging + # Application URLs APP_BASE_URL=http://localhost:4000 CURRENTS_RECORD_API_URL=http://localhost:1234 @@ -121,10 +125,6 @@ AUTOMATED_REPORTS_EMAIL_BCC= # ============================================================================= # These variables configure docker-compose behavior (DC_ prefix = not passed to containers) -# Currents application images -# DC_CURRENTS_IMAGE_REPOSITORY=513558712013.dkr.ecr.us-east-1.amazonaws.com/currents/on-prem/ -# DC_CURRENTS_IMAGE_TAG=staging - # Infrastructure service images (full image reference) # DC_MONGODB_IMAGE=mongo:8.2.3 # DC_REDIS_IMAGE=redis/redis-stack-server:7.4.0-v8 diff --git a/on-prem/CHANGELOG.md b/on-prem/CHANGELOG.md new file mode 100644 index 0000000..4bd14cb --- /dev/null +++ b/on-prem/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +All notable changes to the Currents on-prem Docker Compose deployment will be documented in this file. + +## Unreleased + +- 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/docker-compose.cache.yml b/on-prem/docker-compose.cache.yml index 9554f28..7e48ddb 100644 --- a/on-prem/docker-compose.cache.yml +++ b/on-prem/docker-compose.cache.yml @@ -14,7 +14,7 @@ services: # Currents services depend on redis director: hostname: director - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_DIRECTOR_PORT:-1234}:1234 restart: unless-stopped @@ -31,7 +31,7 @@ services: required: false api: hostname: api - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_API_PORT:-4000}:4000 restart: unless-stopped @@ -50,7 +50,7 @@ services: condition: service_started required: false changestreams-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -65,7 +65,7 @@ services: condition: service_started required: false write-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -80,7 +80,7 @@ services: condition: service_started required: false scheduler: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -98,7 +98,7 @@ services: condition: service_started required: false webhooks: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default diff --git a/on-prem/docker-compose.database.yml b/on-prem/docker-compose.database.yml index 91925ad..398be59 100644 --- a/on-prem/docker-compose.database.yml +++ b/on-prem/docker-compose.database.yml @@ -14,7 +14,7 @@ services: # Currents services depend on redis director: hostname: director - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_DIRECTOR_PORT:-1234}:1234 restart: unless-stopped @@ -37,7 +37,7 @@ services: required: false api: hostname: api - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_API_PORT:-4000}:4000 restart: unless-stopped @@ -62,7 +62,7 @@ services: condition: service_started required: false changestreams-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -83,7 +83,7 @@ services: condition: service_started required: false write-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -104,7 +104,7 @@ services: condition: service_started required: false scheduler: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -128,7 +128,7 @@ services: condition: service_started required: false webhooks: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default diff --git a/on-prem/docker-compose.full.yml b/on-prem/docker-compose.full.yml index 7327ab9..f5c3c34 100644 --- a/on-prem/docker-compose.full.yml +++ b/on-prem/docker-compose.full.yml @@ -14,7 +14,7 @@ services: # Configure Currents services to use path-style S3 URLs (required for RustFS) director: hostname: director - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_DIRECTOR_PORT:-1234}:1234 restart: unless-stopped @@ -38,7 +38,7 @@ services: required: false api: hostname: api - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_API_PORT:-4000}:4000 restart: unless-stopped @@ -64,7 +64,7 @@ services: condition: service_started required: false changestreams-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -86,7 +86,7 @@ services: condition: service_started required: false write-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -108,7 +108,7 @@ services: condition: service_started required: false scheduler: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -133,7 +133,7 @@ services: condition: service_started required: false webhooks: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default diff --git a/on-prem/docs/README.md b/on-prem/docs/README.md index d112e53..8c9608b 100644 --- a/on-prem/docs/README.md +++ b/on-prem/docs/README.md @@ -7,6 +7,7 @@ The Docker Compose configuration is modular, allowing you to choose which data s ## Resources - [🚀 Quickstart Guide](./quickstart.md) +- [Container Image Access](./container-images.md) - [Configuration Reference](./configuration.md) - [Support Policy](./support.md) diff --git a/on-prem/docs/container-images.md b/on-prem/docs/container-images.md new file mode 100644 index 0000000..3b186cf --- /dev/null +++ b/on-prem/docs/container-images.md @@ -0,0 +1,101 @@ +# Container Image Access + +Currents container images are hosted in a private AWS ECR registry. You'll need to set up access and pull/mirror the images before running the services. + +## 1. Create an IAM Role for ECR Access + +Create an IAM role in your AWS account with the following policy: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ecr:GetAuthorizationToken" + ], + "Resource": "*" + }, + { + "Effect": "Allow", + "Action": [ + "ecr:BatchCheckLayerAvailability", + "ecr:BatchGetImage", + "ecr:GetDownloadUrlForLayer" + ], + "Resource": [ + "arn:aws:ecr:us-east-1:513558712013:repository/currents/on-prem/*" + ] + } + ] +} +``` + +## 2. Share Your Role ARN with Currents + +Send the ARN of the IAM role you created to your Currents contact. They will configure cross-account access to allow your role to pull images. + +## 3. Authenticate with ECR + +Once access is granted, authenticate Docker with the Currents ECR registry: + +```bash +# Assume the role (replace with your role ARN) +aws sts assume-role --role-arn --role-session-name currents-access + +# Export the temporary credentials from the response +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_SESSION_TOKEN= + +# Log in to ECR +aws ecr get-login-password --region us-east-1 | \ + docker login --username AWS --password-stdin 513558712013.dkr.ecr.us-east-1.amazonaws.com +``` + +## 4. Mirror Images to Your Registry (Recommended) + +Since ECR credentials expire and your deployment environment may not have AWS access, we recommend mirroring images to your own container registry: + +```bash +# Define source and destination +SOURCE_REGISTRY=513558712013.dkr.ecr.us-east-1.amazonaws.com/currents/on-prem +TARGET_REGISTRY=your-registry.example.com/currents +TAG=staging # or specific version tag + +# List of Currents services +SERVICES="api director change-streams scheduler writer webhooks" + +# Pull, tag, and push each image +for service in $SERVICES; do + docker pull ${SOURCE_REGISTRY}/${service}:${TAG} + docker tag ${SOURCE_REGISTRY}/${service}:${TAG} ${TARGET_REGISTRY}/${service}:${TAG} + docker push ${TARGET_REGISTRY}/${service}:${TAG} +done +``` + +## 5. Configure Docker Compose + +Update your `.env` file to use your mirrored images: + +```bash +# Point to your registry (include trailing slash) +DC_CURRENTS_IMAGE_REPOSITORY=your-registry.example.com/currents/ + +# Specify the image tag +DC_CURRENTS_IMAGE_TAG=staging +``` + +If pulling directly from Currents ECR (not recommended for production): + +```bash +DC_CURRENTS_IMAGE_REPOSITORY=513558712013.dkr.ecr.us-east-1.amazonaws.com/currents/on-prem/ +DC_CURRENTS_IMAGE_TAG=staging +``` + +> **Note:** When pulling directly from ECR, you'll need to re-authenticate periodically as credentials expire after 12 hours. Mirroring to your own registry avoids this operational overhead. + +## Next Steps + +Once you have access to the container images, continue with the [Quickstart Guide](./quickstart.md). diff --git a/on-prem/docs/quickstart.md b/on-prem/docs/quickstart.md index c78e496..f5bc69c 100644 --- a/on-prem/docs/quickstart.md +++ b/on-prem/docs/quickstart.md @@ -7,6 +7,7 @@ This guide walks you through setting up Currents on-premises using Docker Compos - **Docker** 20.10+ with Docker Compose V2, or **Podman** 4.0+ with docker-compose - At least 8GB RAM available for containers - Git (for cloning the repository) +- **Container image access** — see [Container Image Access](./container-images.md) to set up AWS ECR access and mirror images to your registry ## Step 1: Clone the Repository diff --git a/on-prem/templates/compose.currents.yml b/on-prem/templates/compose.currents.yml index 75d845f..1b9a8e6 100644 --- a/on-prem/templates/compose.currents.yml +++ b/on-prem/templates/compose.currents.yml @@ -3,7 +3,7 @@ services: director: hostname: director - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}director:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_DIRECTOR_PORT:-1234}:1234 restart: unless-stopped @@ -17,7 +17,7 @@ services: api: hostname: api - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}api:${DC_CURRENTS_IMAGE_TAG:-staging} ports: - ${DC_API_PORT:-4000}:4000 restart: unless-stopped @@ -33,7 +33,7 @@ services: EMAIL_TRANSPORTER: smtp changestreams-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}change-streams:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -45,7 +45,7 @@ services: EMAIL_TRANSPORTER: smtp write-worker: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}writer:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -57,7 +57,7 @@ services: EMAIL_TRANSPORTER: smtp scheduler: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}scheduler:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default @@ -72,7 +72,7 @@ services: - ${DC_SCHEDULER_STARTUP_VOLUME:-./data/startup}:/app/packages/scheduler/dist/.startup webhooks: - image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-dev} + image: ${DC_CURRENTS_IMAGE_REPOSITORY:-currents-}webhooks:${DC_CURRENTS_IMAGE_TAG:-staging} restart: unless-stopped networks: - default