currents-dev · twk3 · Jan 14, 2026 · Jan 14, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <YOUR_ROLE_ARN> --role-session-name currents-access
+
+# Export the temporary credentials from the response
+export AWS_ACCESS_KEY_ID=<AccessKeyId>
+export AWS_SECRET_ACCESS_KEY=<SecretAccessKey>
+export AWS_SESSION_TOKEN=<SessionToken>
+
+# 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
@@ -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