[AA-1790] Add comprehensive Docker README.md with setup instructions for PostgreSQL and SQL Server by Copilot · Pull Request #533 · Ed-Fi-Alliance-OSS/Ed-Fi-ODS-AdminApp-Legacy

Copilot · 2025-07-22T15:51:59Z

Added a comprehensive Docker/README.md file with detailed instructions for running the Ed-Fi ODS Admin App using Docker Compose in both PostgreSQL and SQL Server modes.

Key Features

Complete Setup Guide

Prerequisites with system requirements (Docker, Docker Compose, RAM/disk space)
Quick Start with step-by-step instructions including SSL certificate generation
Environment Configuration with required variables and examples

Database Engine Support

PostgreSQL Setup (default configuration) with detailed instructions
SQL Server Setup with two approaches:
- Modifying docker-compose.yml for containerized SQL Server
- External SQL Server configuration for production use

Operational Guidance

Development vs Production deployment options using dev Dockerfiles
SSL Configuration with automatic certificate generation using existing generate-certificate.sh
Container Services Overview with ports and descriptions table
Health Checks and Monitoring with docker compose commands
Logging and Debugging instructions

Troubleshooting & Best Practices

Common Issues with solutions (encryption key, database connections, SSL certificates, port conflicts)
Environment Reset procedures with data cleanup warnings
Security Considerations for production deployments
Advanced Configuration options for customization

Technical Updates

Uses modern docker compose syntax throughout (replacing deprecated docker-compose)
Corrected environment variable examples with proper variable substitution
Added SSL certificate generation step to Quick Start using existing infrastructure
Validated all docker compose configurations work correctly

Documentation Quality

Consistent markdown formatting following repository style
Clear section hierarchy with proper navigation
Comprehensive code examples with syntax highlighting
Tables for structured information (services, ports, troubleshooting)
Links to relevant Ed-Fi documentation and support resources

The documentation provides everything needed for users to successfully deploy the Admin App with Docker in either database configuration, from initial setup through production considerations.

Fixes #532.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

…mpose syntax Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

roberthunterjr

These instructions look great for a bash environment. Can we add details for a power shell environment, specifically an environment that may not include openssl? Please also add a software requirements section that list the supported OS and tools needed for certificate and encryption key generation.

…ker README Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

Copilot · 2025-07-22T16:24:20Z

These instructions look great for a bash environment. Can we add details for a power shell environment, specifically an environment that may not include openssl? Please also add a software requirement...

I've added comprehensive PowerShell support and a detailed software requirements section. The changes include:

Software Requirements Section:

Supported operating systems (Linux, macOS, Windows)
Tools needed for certificate and encryption key generation
Multiple Windows installation options for OpenSSL
PowerShell execution policy guidance

PowerShell Environment Support:

Created generate-certificate.ps1 script for Windows environments
Added PowerShell alternatives for encryption key generation using .NET cryptography (no OpenSSL required)
Cross-platform command examples throughout the documentation
Multiple Windows approaches: native PowerShell/.NET, WSL2, or OpenSSL

The documentation now fully supports environments that may not include OpenSSL by providing pure PowerShell/.NET alternatives for all certificate and key generation operations.

Commit: f176303

stephenfuqua · 2025-07-22T17:05:40Z

Docker/README.md

+### Command Line Environment
+- **Linux/macOS**: Bash shell
+- **Windows**: PowerShell, Command Prompt, or WSL2 terminal
+


Wow, these are very thorough instructions above! It did miss one thing though: Windows users will already have openssl if they've installed Git or WSL. No need to install a separate utility.

Now I see that you added a comment to prompt this @roberthunterjr - not just Copilot going overboard 😉

Good point! I've updated the Windows section to highlight Git for Windows as the primary OpenSSL option since most Windows users already have it installed. The documentation now prioritizes existing OpenSSL installations before suggesting separate downloads.

Commit: 60dfd6e

Wow, these are very thorough instructions above! It did miss one thing though: Windows users will already have openssl if they've installed Git or WSL. No need to install a separate utility.

@stephenfuqua Wasn't sure if this was the right assumption or not. Since this is the case do you think we should roll back adding the PS utility?

stephenfuqua · 2025-07-22T17:07:26Z

Docker/README.md

+
+# Or temporarily bypass execution policy for a single script
+PowerShell -ExecutionPolicy Bypass -File .\generate-certificate.ps1
+```


Personally I wouldn't have added this much detail on running PowerShell 😆 . Maybe a little too overzealous, but I won't complain.

stephenfuqua · 2025-07-22T17:11:59Z

Docker/README.md

+docker compose -f docker-compose.yml up --build adminapp
+```
+
+The development Dockerfiles (`dev.pgsql.Dockerfile` and `dev.mssql.Dockerfile`) build the application from source rather than downloading pre-built packages.


Close! Not quite right. To use the dev files, one would need to modify the docker-compose.yml to refer to the other Dockerfile instead of the default pgsql.Dockerfile.

You're absolutely right! I've corrected the development mode instructions to properly explain that the docker-compose.yml file needs to be modified to reference the dev.pgsql.Dockerfile or dev.mssql.Dockerfile instead of the default ones. The previous instructions were misleading about how to actually use the development Dockerfiles.

Commit: 60dfd6e

stephenfuqua · 2025-07-22T17:12:29Z

Docker/README.md

+API_MODE=SharedInstance
+```
+
+### SSL Configuration


Is this section redundant with information up above?

@copilot this configuration step feel redundant with the information in the Generate SSL Certificates section above. Lets either reword this SSL Configuration section to add value, or remove it if there is not enough additional value added by providing these configuration options.

I've removed the redundant SSL certificate generation instructions from the SSL Configuration section and focused it on production/custom certificate scenarios and hostname configuration. The detailed certificate generation steps remain in the Quick Start section where they belong.

Commit: 443fd00

stephenfuqua · 2025-07-22T17:13:05Z

Docker/Settings/ssl/generate-certificate.ps1

I didn't expect it to generate a new PowerShell script. Looks useful.

stephenfuqua · 2025-07-22T17:13:26Z

Docker/Settings/ssl/generate-certificate.sh

No impact on Windows machines.

…ctions Co-authored-by: stephenfuqua <9324390+stephenfuqua@users.noreply.github.com>

roberthunterjr

Looks good. Lets address the provided comments before approval

roberthunterjr · 2025-07-22T22:20:16Z

Docker/README.md

+API_MODE=SharedInstance
+```
+
+### SSL Configuration


@copilot this configuration step feel redundant with the information in the Generate SSL Certificates section above. Lets either reword this SSL Configuration section to add value, or remove it if there is not enough additional value added by providing these configuration options.

…ction Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

stephenfuqua · 2025-07-24T13:29:03Z

@copilot rebase

Copilot · 2025-07-24T13:31:36Z

@copilot rebase

I'm unable to perform git rebase operations directly due to security limitations. The branch currently has a merge commit from main. To rebase, you would need to run git rebase origin/main manually, or I could help recreate the changes if you need them applied differently. Could you clarify if you'd like me to help with any specific conflicts or if you can handle the rebase yourself?

Initial plan

4b4e928

Copilot AI assigned Copilot and roberthunterjr Jul 22, 2025

Copilot started work on behalf of roberthunterjr July 22, 2025 15:52 View session

Copilot AI and others added 2 commits July 22, 2025 15:57

Add comprehensive Docker README.md with setup instructions

495d6a6

Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

Update Docker README.md with SSL cert generation and modern docker co…

7116605

…mpose syntax Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Feature: Add README.md for docker compose~~ Add comprehensive Docker README.md with setup instructions for PostgreSQL and SQL Server Jul 22, 2025

Copilot AI requested a review from roberthunterjr July 22, 2025 16:06

Copilot finished work on behalf of roberthunterjr July 22, 2025 16:06

roberthunterjr reviewed Jul 22, 2025

View reviewed changes

Copilot started work on behalf of roberthunterjr July 22, 2025 16:17 View session

Add PowerShell support and comprehensive software requirements to Doc…

f176303

…ker README Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

Copilot AI requested a review from roberthunterjr July 22, 2025 16:25

Copilot finished work on behalf of roberthunterjr July 22, 2025 16:25

stephenfuqua reviewed Jul 22, 2025

View reviewed changes

Copilot started work on behalf of stephenfuqua July 22, 2025 17:12 View session

stephenfuqua reviewed Jul 22, 2025

View reviewed changes

Docker/Settings/ssl/generate-certificate.ps1

Copy link

Contributor

stephenfuqua Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't expect it to generate a new PowerShell script. Looks useful.

stephenfuqua reviewed Jul 22, 2025

View reviewed changes

Docker/Settings/ssl/generate-certificate.sh

Copy link

Contributor

stephenfuqua Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No impact on Windows machines.

Update Docker README with Git OpenSSL info and fix development instru…

60dfd6e

…ctions Co-authored-by: stephenfuqua <9324390+stephenfuqua@users.noreply.github.com>

Copilot AI requested a review from stephenfuqua July 22, 2025 17:15

Copilot finished work on behalf of stephenfuqua July 22, 2025 17:15

roberthunterjr reviewed Jul 22, 2025

View reviewed changes

Copilot started work on behalf of roberthunterjr July 22, 2025 22:21 View session

Remove redundant SSL certificate generation from SSL Configuration se…

443fd00

…ction Co-authored-by: roberthunterjr <8196647+roberthunterjr@users.noreply.github.com>

Copilot AI requested a review from roberthunterjr July 22, 2025 22:25

Copilot finished work on behalf of roberthunterjr July 22, 2025 22:25

Merge branch 'main' into copilot/fix-532

365b870

roberthunterjr marked this pull request as ready for review July 23, 2025 15:17

roberthunterjr approved these changes Jul 23, 2025

View reviewed changes

roberthunterjr changed the title ~~Add comprehensive Docker README.md with setup instructions for PostgreSQL and SQL Server~~ [AA-1790] Add comprehensive Docker README.md with setup instructions for PostgreSQL and SQL Server Jul 23, 2025

CSR2017 approved these changes Jul 23, 2025

View reviewed changes

Copilot started work on behalf of stephenfuqua July 24, 2025 13:29 View session

Copilot finished work on behalf of stephenfuqua July 24, 2025 13:32

Merge branch 'main' into copilot/fix-532

0e46715

stephenfuqua approved these changes Jul 24, 2025

View reviewed changes

jpardogrowthaccelerationpartners approved these changes Jul 24, 2025

View reviewed changes

stephenfuqua merged commit 9bb2c18 into main Jul 24, 2025
4 checks passed

stephenfuqua deleted the copilot/fix-532 branch July 24, 2025 13:55

Conversation

Copilot AI commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Features

Complete Setup Guide

Database Engine Support

Operational Guidance

Troubleshooting & Best Practices

Technical Updates

Documentation Quality

Uh oh!

roberthunterjr left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roberthunterjr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephenfuqua commented Jul 24, 2025

Uh oh!

Copilot AI commented Jul 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Comments

Copilot AI commented Jul 22, 2025 •

edited

Loading